api-designer

Skill: API Designer

Category: Dev Expert Version: 1.0.0 Used By: backend-nodejs, backend-python, backend-go, backend-laravel

Overview

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

1. RESTful Conventions

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

3. Versioning Strategies

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

6. Pagination Patterns

Offset-based (Simple)

GET /users?page=2&page_size=20

Cursor-based (Scalable)

GET /users?cursor=eyJpZCI6MTAwfQ&limit=20

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

Version: 1.0.0 | Last Updated: 2025-11-28