Imported from Yisuescopeta/OpenGame (
.agent/skills/api-design/SKILL.md). Install upstream withnpx skills add Yisuescopeta/OpenGame --skill api-design. Copyright stays with the author (MIT).
API Design Principles
Overview
Great APIs are consistent, predictable, and easy to use. This skill enforces industry standards for API design.
Core Principles
1. Resource-Oriented Design (REST)
- Nouns, not Verbs: Use resources (nouns) in methods.
- Good:
GET /users,POST /users - Bad:
GET /getUsers,POST /createUser
- Good:
- Plural Nouns: Use plural nouns for collections (
/usersnot/user). - Nesting: Use nesting to show relationships, but limit depth to 2-3 levels.
GET /users/{id}/posts(Okay)GET /users/{id}/posts/{pid}/comments(Borderline)
2. HTTP Methods
- GET: Retrieve data. Safe and idempotent.
- POST: Create new resources. Not idempotent.
- PUT: Update/Replace a resource completely. Idempotent.
- PATCH: Partial update. Idempotent.
- DELETE: Remove a resource. Idempotent.
3. Responses & Status Codes
- 200 OK: Success (GET, PUT, PATCH).
- 201 Created: Success (POST) - Return the created resource.
- 204 No Content: Success (DELETE) - No body returned.
- 400 Bad Request: Client error (validation).
- 401 Unauthorized: Missing/invalid authentication.
- 403 Forbidden: Authenticated but not allowed.
- 404 Not Found: Resource does not exist.
- 500 Internal Server Error: Server bug.
4. Naming Conventions
- Case: Use
camelCasefor JSON fields and params (e.g.,firstName). Usekebab-casefor URLs (e.g.,/user-profiles). - Consistency: If you use
userIdin one place, don't useuser_idoridelsewhere for the same concept.
5. Filtering, Sorting, Pagination
- Pagination: Always paginate collections. Use
limitandoffsetor cursor-based pagination. - Filtering: Use query parameters:
GET /users?role=admin. - Sorting: Use
sortororder:GET /users?sort=-createdAt(descending).
6. GraphQL Specifics
- Schema First: Design the schema before implementation.
- N+1 Problem: Ensure resolvers use DataLoaders to batch database requests.
- Naming: Use verb-noun for mutations (
createUser,updatePost).
Security
- HTTPS: Always use HTTPS.
- Authentication: Use Bearer Tokens (JWT) in headers.
- Rate Limiting: Protect endpoints from abuse.
