Agent skill · software engineering · personamanagmentlayer
api-design-expert
Expert-level API design principles, REST, GraphQL, versioning, and API best practices. Use when the user mentions REST, GraphQL, API versioning, or API security, or when the task involves API Design Principles, API Styles, or Documentation.
Why this skill is useful
Provides specific implementation patterns and best practices for REST and GraphQL APIs that the AI wouldn't reliably generate on its own.
What it needs
About 5k tokens when loaded. Last updated 2026-03-30. 41 stars on the source repository.
What this skill does
API Design Expert Expert guidance for API design, RESTful principles, GraphQL, versioning strategies, and API best practices. Core Concepts API Design Principles RESTful architecture Resource-oriented design Uniform interface Statelessness Cacheability Layered system API Styles REST (Representational State Transfer) GraphQL RPC (Remote Procedure Call) WebSocket Server-Sent Events (SSE) gRPC Key Considerations Versioning strategies Authentication and authorization Rate limiting Error handling Documentation Backward compatibility REST API Design API Versioning Error Handling Rate Limiting HATEOAS Implementation API Security Best Practices Design Use nouns for resources, not verbs Use plural names for collections Use HTTP methods correctly (GET, POST, PUT, PATCH, DELETE) Return appropriate status codes Support filtering, sorting, and pagination Use consistent naming conventions Version APIs from the start Documentation Use OpenAPI/Swagger Provide example requests and responses Document error codes and messages Include authentication requirements Keep documentation up-to-date Provide SDKs when possible Performance Implement caching (ETags, Cache-Control) Support compression (gzip) Paginate large result sets Use async operations for long tasks Implement rate limiting Monitor API performance Security Use HTTPS always Implement authentication and authorization Validate all inputs Rate limit to prevent abuse Log security events Use API keys or OAuth 2.0 Implement CORS properly Anti-Patterns ❌ Using GET for state-changing operations ❌ Returning inconsistent response formats ❌ No versioning strategy ❌ Poor error messages ❌ No rate limiting ❌ Exposing internal implementation details ❌ Breaking changes without versioning Resources REST API Design Best Practices: https://restfulapi.net/ OpenAPI Specification: https://swagger.io/specification/ API Design Guide: https://cloud.google.com/apis/design Microsoft REST API Guidelines: https://github.com/microsoft/api-guidelines FastAPI: …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills personamanagmentlayer/api-design-expert