api-design

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:

GET    /api/v1/users           # List users
GET    /api/v1/users/{id}      # Get user
POST   /api/v1/users           # Create user
PUT    /api/v1/users/{id}      # Update user
PATCH  /api/v1/users/{id}      # Partial update
DELETE /api/v1/users/{id}      # Delete user

Step 3: Request/Response format

Request example:

POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]",
  "role": "admin"
}

Response example:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123

{
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}