Agent skill · software engineering · aiskillstore
api-design
Design RESTful and GraphQL APIs following best practices. Use when creating new APIs, refactoring existing endpoints, or documenting API specifications. Handles OpenAPI, REST, GraphQL, versioning.
Why this skill is useful
Provides specific patterns and best practices for designing RESTful and GraphQL APIs that the AI wouldn't reliably generate on its own.
What it needs
About 3k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
API Design When to use this skill Designing new REST APIs Creating GraphQL schemas Refactoring API endpoints Documenting API specifications API versioning strategies Defining data models and relationships Instructions Step 1: Define API requirements Identify resources and entities Define relationships between entities Specify operations (CRUD, custom actions) Plan authentication/authorization Consider pagination, filtering, sorting Step 2: Design REST API Resource naming: Use nouns, not verbs: /users not /getUsers Use plural names: /users/{id} Nest resources logically: /users/{id}/posts Keep URLs short and intuitive HTTP methods: GET: Retrieve resources (idempotent) POST: Create new resources PUT: Replace entire resource PATCH: Partial update DELETE: Remove resources (idempotent) Response codes: 200 OK: Success with response body 201 Created: Resource created successfully 204 No Content: Success with no response body 400 Bad Request: Invalid input 401 Unauthorized: Authentication required 403 Forbidden: No permission 404 Not Found: Resource doesn't exist 409 Conflict: Resource conflict 422 Unprocessable Entity: Validation failed 500 Internal Server Error: Server error Example REST endpoint: Step 3: Request/Response format Request example: Response example: Step 4: Error handling Error response format: Step 5: Pagination Query parameters: Response with pagination: Step 6: Authentication Options: JWT (JSON Web Tokens) OAuth 2.0 API Keys Session-based Example with JWT: Step 7: Versioning URL versioning (recommended): Header versioning: Step 8: Documentation Create OpenAPI 3.0 specification: Best practices 1. Consistency: Use consistent naming, structure, and patterns 2. Versioning: Always version your APIs from the start 3. Security: Implement authentication and authorization 4. Validation: Validate all inputs on the server side 5. Rate limiting: Protect against abuse 6. Caching: Use ETags and Cache-Control headers 7. CORS: Configure properly for web clients 8. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/api-design--c897c2