Agent skill · software engineering · aj-geddes
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.
Why this skill is useful
Provides specific guidelines and best practices for designing RESTful APIs that the AI may not reliably generate on its own.
What it needs
About 1k tokens when loaded. Last updated 2026-03-04. 307 stars on the source repository.
What this skill does
REST API Design Table of Contents Overview When to Use Quick Start Reference Guides Best Practices Overview Design REST APIs that are intuitive, consistent, and follow industry best practices for resource-oriented architecture. When to Use Designing new RESTful APIs Creating endpoint structures Defining request/response formats Implementing API versioning Documenting API specifications Refactoring existing APIs Quick Start Minimal working example: Reference Guides Detailed implementations in the references/ directory: Guide Contents --- --- Resource Naming Resource Naming, HTTP Methods & Operations Request Examples Request Examples Query Parameters Query Parameters Response Formats Response Formats HTTP Status Codes HTTP Status Codes, API Versioning, Authentication & Security, Rate Limiting Headers OpenAPI Documentation OpenAPI Documentation Complete Example: Express.js const express = require("express"); Best Practices ✅ DO Use nouns for resources, not verbs Use plural names for collections Be consistent with naming conventions Return appropriate HTTP status codes Include pagination for collections Provide filtering and sorting options Version your API Document thoroughly with OpenAPI Use HTTPS Implement rate limiting Provide clear error messages Use ISO 8601 for dates ❌ DON'T Use verbs in endpoint names Return 200 for errors Expose internal IDs unnecessarily Over-nest resources (max 2 levels) Use inconsistent naming Forget authentication Return sensitive data Break backward compatibility without versioning
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aj-geddes/rest-api-design