api-design

Imported from Yisuescopeta/OpenGame (.agent/skills/api-design/SKILL.md). Install upstream with npx 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
• Plural Nouns: Use plural nouns for collections (/users not /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 camelCase for JSON fields and params (e.g., firstName). Use kebab-case for URLs (e.g., /user-profiles).
• Consistency: If you use userId in one place, don't use user_id or id elsewhere for the same concept.

5. Filtering, Sorting, Pagination

• Pagination: Always paginate collections. Use limit and offset or cursor-based pagination.
• Filtering: Use query parameters: GET /users?role=admin.
• Sorting: Use sort or order: 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.