api-design

API Design

This skill enables an AI agent to design production-quality RESTful APIs. The agent models resources, defines endpoints with correct HTTP method semantics, selects appropriate status codes, implements pagination and versioning strategies, and produces OpenAPI documentation. The output follows REST constraints including statelessness, uniform interface, and resource-based URIs.

Workflow

1. Identify resources and relationships: Analyze the application domain to extract nouns as resources (e.g., users, tasks, comments). Map relationships between resources—one-to-many, many-to-many—and determine whether sub-resources or independent collections are appropriate. Avoid verb-based endpoints; resources should represent entities, not actions.

2. Define endpoints and HTTP methods: For each resource, define CRUD endpoints using the correct HTTP methods. Use GET for retrieval (safe, idempotent), POST for creation (not idempotent), PUT for full replacement (idempotent), PATCH for partial updates (idempotent), and DELETE for removal (idempotent). Nest sub-resources under their parent when the relationship is strong (e.g., /tasks/{id}/comments).

3. Design request and response schemas: Define JSON request bodies, response payloads, and query parameters for each endpoint. Include field names in snake_case or camelCase consistently. Specify required vs. optional fields, data types, and validation constraints. Design a consistent error response envelope used across all endpoints.

4. Implement pagination, filtering, and sorting: For list endpoints, add cursor-based or offset pagination with limit and offset (or cursor) query parameters. Support filtering via query parameters (e.g., ?status=active) and sorting with sort and order parameters. Return pagination metadata in the response body including total count, next/previous links.

5. Define versioning and content negotiation: Choose a versioning strategy—URI path (/v1/tasks), query parameter (?version=1), or Accept header (Accept: application/vnd.api.v1+json). URI path versioning is simplest and most common. Ensure backward compatibility within a version and document deprecation timelines.