Api Design

API Design

An API is a contract. Breaking changes break trust. Design for the long term.

Endpoint Design (REST)

Naming

• Nouns, not verbs: /users not /getUsers
• Plural resources: /users, /orders, /posts
• Nested for ownership: /users/{id}/orders
• Consistent casing: kebab-case for URLs (/user-profiles), camelCase or snake_case for JSON fields (pick one, stick to it)

HTTP Methods

| Method | Use | Idempotent | |--------|-----|-----------| | GET | Read resource(s) | Yes | | POST | Create resource | No | | PUT | Replace resource entirely | Yes | | PATCH | Partial update | Yes | | DELETE | Remove resource | Yes |

Status Codes

| Code | When | |------|------| | 200 | Success with body | | 201 | Created (POST success) | | 204 | Success, no body (DELETE) | | 400 | Bad request (validation error) | | 401 | Not authenticated | | 403 | Authenticated but not authorized | | 404 | Resource not found | | 409 | Conflict (duplicate, state conflict) | | 422 | Semantically invalid (valid JSON, wrong values) | | 429 | Rate limited | | 500 | Server error (never intentional) |

Request / Response Design

Requests

• Required fields are required. Don't silently default missing required data.
• Validate early, fail fast. Return all validation errors at once, not one at a time.
• Accept only what you need. Ignore extra fields or reject them - pick a policy and be consistent.

Responses

• Consistent envelope (or no envelope - just be consistent):

``json { "data": { ... }, "meta": { "page": 1, "total": 42 } } ``

• Include id and created_at on every resource.
• Return the created/updated resource on mutation (saves a follow-up GET).
• Never expose internal IDs, database details, or stack traces.

Error Handling

Consistent error format across all endpoints:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

• Machine-readable code (for programmatic handling)
• Human-readable message (for logging/debugging)
• details array for field-level errors
• Same shape for every error, every endpoint

Pagination

For list endpoints returning potentially large datasets:

Cursor-Based (Preferred)

GET /posts?after=cursor_abc&limit=20
→ { "data": [...], "meta": { "next_cursor": "cursor_def", "has_more": true } }

• Stable under insertions/deletions
• No "page 3 is now different" problem

Offset-Based (Simpler)

GET /posts?page=2&per_page=20
→ { "data": [...], "meta": { "page": 2, "per_page": 20, "total": 142 } }

• Familiar to consumers
• Breaks when data changes between pages

Versioning

• Version when you make breaking changes (removed fields, changed types, new required params).
• Don't version for additive changes (new optional fields, new endpoints).
• URL path versioning: /v1/users, /v2/users - simplest, most visible.
• Support at most 2 versions simultaneously. Old version gets a sunset date.

Rate Limiting

• Return 429 Too Many Requests with Retry-After header.
• Document limits clearly.
• Different limits for different operations (reads vs writes).
• Include rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

API Review Checklist

• [ ] Naming is consistent with existing endpoints
• [ ] Appropriate HTTP methods and status codes
• [ ] Request validation returns helpful errors
• [ ] Response doesn't over-fetch (no unnecessary fields)
• [ ] Pagination on list endpoints
• [ ] Authentication/authorization checked
• [ ] Rate limiting considered
• [ ] Breaking changes versioned
• [ ] Error format matches the standard

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pvnarp
• Source: pvnarp/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.