skills.rest
pkuppens
pkuppensCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design

Enforce REST conventions, versioning, and OpenAPI documentation for API endpoints.

1|Updated May 30, 2025
Search Tags:#code review#api design#openapi#rest#endpoint#api governance
One-click install
npx skills add https://github.com/pkuppens/on_prem_rag --skill api-design-pkuppens
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/pkuppens/on_prem_rag/tree/main/.cursor/skills/api-design
Command: npx skills add https://github.com/pkuppens/on_prem_rag --skill api-design-pkuppens

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill ensures that new and modified API endpoints adhere to established design principles, promoting consistency, maintainability, and clarity in API development.

Core Features & Use Cases

  • Enforces REST Conventions: Guides the correct use of HTTP verbs and status codes.
  • Standardizes Resource Naming: Promotes clear and hierarchical URL structures.
  • Manages Endpoint Evolution: Helps decide when to create new endpoints versus extending existing ones.
  • Prevents Anti-Patterns: Identifies and rectifies common API design flaws like duplicate endpoints or overlapping semantics.
  • Ensures Documentation: Mandates OpenAPI metadata for better discoverability and usability.
  • Use Case: Before merging a pull request for a new /api/users/{id}/profile endpoint, this Skill is invoked to verify it follows plural noun conventions, uses the appropriate HTTP method (e.g., GET), and has complete OpenAPI documentation.

Quick Start

Use the api-design skill to review the proposed new endpoint for user profiles.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce REST conventions and prevent duplicate endpoints in API design?▼

API design enforcement validates HTTP verbs, resource naming, and OpenAPI documentation standards to prevent duplicate endpoints and overlapping semantics in new and modified API endpoints.

What are common API anti-patterns and how do I check for overlapping semantics?▼

Common API anti-patterns include duplicate endpoints and overlapping semantics. You can identify and rectify these flaws by enforcing API design rules that validate adherence to REST conventions and deduplication semantics.

Does this API governance approach require OpenAPI documentation standards?▼

Yes, API governance enforcement mandates OpenAPI metadata for new and changing endpoints to ensure better discoverability and usability, validating complete OpenAPI documentation standards before merging.

How do I manage endpoint versioning and decide when to create new REST endpoints?▼

Endpoint versioning management applies REST conventions and versioning semantics to decide when to create new endpoints versus extending existing ones, ensuring maintainability and clarity during API evolution.

Can I use API design rules to review a pull request for a new OpenAPI endpoint?▼

Yes, you can invoke API design rules during code review to verify a new endpoint follows plural noun conventions, uses the appropriate HTTP method, and has complete OpenAPI documentation before merging.

Related Skills

Explore More Software Engineering Skills→
jhlee0409jhlee0409
4

openapi-parser

Parse OpenAPI 3.x and Swagger 2.0 specs into structured endpoint catalogs.

Community
Advanced
Adelie-SquadAdelie-Squad
17

api-developer

Design API contracts and generate OpenAPI 3.0 documentation.

Official
Advanced
rfhaynrfhayn
2

review

Review Git branches and pull requests for convention and code quality compliance.

Community
Advanced
mvandermeulenmvandermeulen
2

openapi-spec-generation

Generate and maintain OpenAPI 3.1 specifications with validation and SDK generation.

Community
Advanced