Rest Api Design

What it does

This skill assists in designing RESTful APIs, focusing on proper conventions and a positive developer experience. It provides guidance on resource naming (using nouns), appropriate HTTP methods for different actions (GET, POST, PUT, PATCH, DELETE), standard status codes, response formatting including data, meta information, pagination, and query parameters. The goal is to help create well-structured and documented backend APIs.

When to use it

• When designing new REST APIs or microservices.
• To review existing API designs for adherence to RESTful principles.
• For guidance on choosing the correct HTTP methods (GET, POST, PUT, PATCH, DELETE) for specific actions.
• To understand and implement proper status code usage in API responses.
• When implementing pagination or filtering of data returned by an API endpoint.

Key capabilities

• Resource Naming: Guidance on using nouns instead of verbs in resource URLs (e.g., /api/users vs. /api/getUsers).
• HTTP Methods: Explanation and use cases for GET, POST, PUT, PATCH, and DELETE methods.
• Status Codes: Provides a reference for common HTTP status codes (200, 201, 204, 400, 401, 403, 404, 429) and their appropriate usage.
• Response Formatting: Examples of response formats including data sections, meta information, and pagination details.
• Query Parameters: Demonstrates how to use query parameters for filtering, sorting, pagination, and field selection.

Example prompts

• "I need help designing an API endpoint for creating new users. What HTTP method should I use?"
• "What are some best practices for naming resources in a RESTful API?"
• "Can you show me an example of a response format including pagination?"
• "What status code should I return when a resource is successfully deleted?"

Tips & gotchas

• The skill focuses on RESTful design principles and doesn't cover implementation details or specific programming languages.
• Version your APIs using URL paths (e.g., /api/v1/) for backwards compatibility.
• Consider documenting your API with OpenAPI/Swagger for improved developer understanding.