Api Design

What it does

This skill assists in designing REST APIs, covering key aspects from URL structure to error handling and versioning. It provides guidance on standard HTTP methods (GET, POST, PUT, PATCH, DELETE), nested resources, and appropriate HTTP status codes for various scenarios. The skill also outlines best practices for request/response design including pagination, single resource responses, and structured error reporting.

When to use it

• When designing a new backend service or API workflow.
• To ensure adherence to REST API design principles.
• For guidance on structuring URLs and handling HTTP status codes correctly.
• To understand how to format request and response bodies for clarity and consistency.
• When implementing query parameters for filtering, sorting, pagination, field selection, and searching.

Key capabilities

• Provides examples of REST API URL structures (e.g., GET /api/v1/resources/{id}).
• Defines common HTTP status codes and their appropriate usage (200 OK, 404 Not Found, etc.).
• Illustrates collection and single resource response formats.
• Explains how to structure error responses with code, message, and details.
• Covers query parameter patterns for filtering, sorting, pagination, field selection, and searching.
• Addresses idempotency considerations for POST, PUT, and DELETE requests.
• Outlines URL path versioning strategies for API evolution.

Example prompts

• "Show me an example of a REST endpoint to create a new resource."
• "What HTTP status code should I return when a resource is not found?"
• "How can I implement pagination in my API response?"
• “Give me examples of query parameters for filtering resources by status and type.”

Tips & gotchas

• This skill focuses on REST API design principles; it does not provide coding implementation details.
• The skill emphasizes input validation at the API boundary as a security consideration.
• It recommends using parameterized queries to prevent SQL injection vulnerabilities (though it notes JOOQ handles this).