rest-api-design

Design RESTful APIs following best practices for resource modeling, HTTP methods, status codes, versioning, and documentation. Use when creating new APIs, designing endpoints, or improving existing API architecture.

294stars45forksUpdated 7/17/2026

#http #openapi #api-design #documentation #backend #rest-api

Security Assessment

Safe(100/100)

Security Score100/100

About rest-api-design

rest-api-design helps design RESTful APIs that follow established best practices for resource modeling, HTTP methods, status codes, versioning, and documentation. It is intended for creating new APIs, designing endpoint structures, defining request and response formats, implementing versioning, documenting specifications, and refactoring existing APIs toward a consistent resource-oriented architecture. The goal is APIs that are intuitive, consistent, and aligned with industry conventions.

The skill leads with a quick-start contrast between good resource names (nouns, plural, e.g. GET /api/users, GET /api/users/123/orders, POST /api/products) and bad ones (verbs and inconsistent singular/plural, e.g. GET /api/getUsers, POST /api/createProduct). It backs this with detailed reference guides in the references/ directory covering resource naming and HTTP methods, request examples, query parameters, response formats, HTTP status codes (including API versioning, authentication and security, and rate limiting headers), OpenAPI documentation, and a complete Express.js example. It also ships a validate-api.sh script and an api-scaffold.yaml template. A best-practices section codifies DO items such as using plural nouns, returning appropriate status codes, paginating collections, offering filtering and sorting, versioning the API, documenting thoroughly with OpenAPI, using HTTPS, implementing rate limiting, and using ISO 8601 dates, alongside DON'T items like using verbs in endpoints, returning 200 for errors, over-nesting resources beyond two levels, and breaking backward compatibility without versioning.

The skill targets backend engineers, API designers, and teams standardizing their API conventions. It is reference-driven, pairing concise principles in SKILL.md with deeper material in the references/ files and a runnable validation script, so it suits both greenfield design and refactoring of existing endpoints. Its scope is API design guidance and documentation patterns rather than a specific framework or runtime, with the Express.js example serving as a concrete implementation illustration.

FAQ

When should I use this skill?

Use it when designing new RESTful APIs, creating endpoint structures, defining request and response formats, implementing API versioning, documenting API specifications with OpenAPI, or refactoring existing APIs toward consistent conventions.

What reference material is included?

The references/ directory covers resource naming and HTTP methods, request examples, query parameters, response formats, HTTP status codes (with versioning, authentication/security, and rate limiting headers), OpenAPI documentation, and a complete Express.js example. There is also a validate-api.sh script and an api-scaffold.yaml template.

What are the core naming conventions it recommends?

Use nouns rather than verbs, plural names for collections, and consistent naming (e.g., GET /api/users and GET /api/users/123/orders). Avoid verb-based endpoints like /api/getUsers or /api/createProduct and inconsistent singular/plural forms.

What practices does it explicitly warn against?

Don't use verbs in endpoint names, don't return 200 for errors, don't expose internal IDs unnecessarily, don't over-nest resources beyond two levels, don't use inconsistent naming, don't forget authentication, don't return sensitive data, and don't break backward compatibility without versioning.