api-designer

Skill: API Designer

Category: Dev Expert Used By: architect, backend-python, backend-go, backend-laravel

---

Overview

Design consistent, RESTful APIs with proper versioning, documentation, and error handling.

---

1. RESTful Conventions

Method	Endpoint	Purpose	Response
GET	/users	List all	200 + array
GET	/users/:id	Get one	200 / 404
POST	/users	Create	201 + created
PUT	/users/:id	Replace	200 / 404
PATCH	/users/:id	Update	200 / 404
DELETE	/users/:id	Delete	204 / 404

Nested Resources

GET    /users/:userId/orders          # User's orders
POST   /users/:userId/orders          # Create order for user
GET    /users/:userId/orders/:orderId # Specific order

---

2. Naming Conventions

Type	Convention	Example
Resources	Plural nouns	/users, /orders
Actions	Verbs (rare)	/auth/login, /reports/generate
Query params	snake_case	?page_size=20
Request/Response	camelCase	{ "firstName": "John" }

---

3. Versioning Strategies

Strategy	Example	When to Use
URL Path	/v1/users	Most common, clear
Header	Accept: application/vnd.api+json;version=1	Clean URLs
Query	/users?version=1	Simple but messy

Recommended: URL path (/api/v1/...)

---

4. Response Format

Success

{
  "data": { "id": "123", "name": "John" },
  "meta": { "timestamp": "2025-01-01T00:00:00Z" }
}

List with Pagination

{
  "data": [{ "id": "1" }, { "id": "2" }],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "fields": { "email": "Invalid format" }
  }
}

---

5. Status Codes

Code	Meaning	When to Use
200	OK	Successful GET/PUT/PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Invalid input
401	Unauthorized	No/invalid auth
403	Forbidden	No permission
404	Not Found	Resource missing
409	Conflict	Duplicate/state conflict
422	Unprocessable	Validation failed
429	Too Many	Rate limited
500	Server Error	Unexpected error

---

6. Pagination Patterns

Offset-based (Simple)

GET /users?page=2&page_size=20

Cursor-based (Scalable)

GET /users?cursor=eyJpZCI6MTAwfQ&limit=20

Pattern	Pros	Cons
Offset	Simple, jump to page	Slow on large datasets
Cursor	Consistent, fast	No page jumping

---

7. Filtering & Sorting

# Filter
GET /users?status=active&role=admin

# Sort
GET /users?sort=created_at:desc,name:asc

# Search
GET /users?q=john

# Combined
GET /users?status=active&sort=name:asc&page=1&page_size=20

---

8. API Documentation (OpenAPI)

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

---

9. API Design Checklist

• RESTful resource naming
• Consistent response format
• Proper status codes
• Pagination for lists
• Error responses with codes
• Versioning strategy
• OpenAPI documentation
• Rate limiting headers

---

Best Practices

Do's

• Use plural nouns for resources
• Return created/updated resource
• Include pagination metadata
• Document with OpenAPI
• Version from day one

Don'ts

• Use verbs in resource names
• Return different formats per endpoint
• Expose internal IDs/structures
• Ignore backward compatibility
• Skip error code standards

---