api-design_skill

Overview

This skill provides practical RESTful API design guidance to help teams create consistent, usable, and scalable HTTP APIs. It codifies naming, versioning, error handling, response formats, and common query patterns so you can design endpoints that are easy to consume and evolve. Use it as a checklist and reference when defining endpoints or reviewing existing APIs.

How this skill works

The skill inspects API surface decisions: resource naming, URL structure, HTTP method semantics, status code usage, response envelopes, pagination, filtering, and versioning strategy. It verifies consistency against best-practice rules (plural nouns, lowercase and hyphens, limited nesting) and identifies gaps such as missing pagination, unclear error payloads, or absent versioning. It outputs concrete recommendations to align designs with common RESTful conventions.

When to use it

• Designing new REST endpoints or an API surface
• Writing or reviewing API documentation and contracts
• Evaluating an existing API for consistency and usability
• Defining pagination, filtering, sorting, and field-selection behavior
• Planning versioning and backward-compatible changes

Best practices

• Model URLs around resources using plural nouns (e.g., /users, /orders) and keep paths lowercase with hyphens
• Use HTTP methods semantically: GET for read, POST for create, PUT for full update, PATCH for partial update, DELETE for removal
• Return appropriate status codes (200/201/204 for success, 400/401/403/404/422/500 for errors) and avoid overloading 200 for failures
• Standardize response envelopes: include data, meta/pagination, and a consistent error object with code, message, and details
• Support pagination, filtering, sorting, and field selection via query parameters to keep responses efficient
• Version via the URL (e.g., /api/v1/) to enable safe evolution without breaking clients

Example use cases

• Define a users service: /api/v1/users, GET/POST, GET /users/{id}, PATCH /users/{id}
• Design a list endpoint with pagination and filters: GET /products?page=1&per_page=20&status=active
• Create a consistent error contract for validation failures with error.code and error.details
• Review an existing API and produce a checklist-based report: naming, status codes, pagination, versioning
• Plan API version upgrade: map breaking changes and add /api/v2/ endpoints while keeping /api/v1/ stable