Overview

api-designer provides expert guidance for building clean, consistent REST APIs. It covers REST principles, URL design, response formats, versioning, security, and thorough documentation to improve usability and maintainability.

How This Skill Works

Design decisions are driven by REST principles, consistent URL structures, and explicit response formats. It advocates pluralized collections, logical nesting, and query-based filtering/pagination, with consistent JSON responses and collection metadata. It also covers versioning, security, input validation, rate limiting, and OpenAPI documentation to support maintainability.

When to Use It

• Design a new public REST API from scratch.
• Audit an existing API for consistency and usability.
• Add versioning, deprecation notices, and backward compatibility.
• Enforce security best practices: HTTPS, auth, validation, rate limiting.
• Create OpenAPI specs with request/response examples and error codes.

Quick Start

1. Step 1: Map resources to nouns, set plural URLs, and design nested paths (e.g., /users/{id}/posts).
2. Step 2: Define HTTP methods, status codes, and a consistent JSON structure with collection metadata.
3. Step 3: Add versioning, security (HTTPS, auth, validation, rate limiting) and generate/OpenAPI docs; publish and maintain them.

Best Practices

• Use nouns for resources and verbs for actions; apply HTTP method semantics.
• Use plural nouns for collections, nest resources logically, and enable filtering/pagination via query parameters.
• Return a consistent JSON structure with metadata for collections and clear error messages; support partial responses if needed.
• Version APIs in URL or headers; document breaking changes; deprecate gracefully.
• Secure APIs with HTTPS, proper authentication, input validation, rate limiting, and thorough security event logging; maintain OpenAPI docs.

Example Use Cases

• A paginated /users response includes metadata like total, page, and perPage.
• Nested resources example: /users/123/posts to fetch posts for a specific user.
• Versioned endpoints under /v1/ (e.g., /v1/users) with backward-compatible changes.
• Error responses include meaningful messages and appropriate HTTP status codes (400, 404, 422).
• An OpenAPI/Swagger spec with example requests and responses is provided and kept up to date.

Frequently Asked Questions