Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    REST API Design: APIs Developers Love

    1

    Design or review REST APIs: naming, methods and status codes, RFC 9457 errors, cursor pagination, filtering, idempotency keys, ETags, versioning, auth, rate limits, webhooks and a complete OpenAPI 3.1 spec with examples.

    Free

    7 uses5.0 (1 review)
    REST API Design: APIs Developers Love

    REST API Design: APIs Developers Love

    Example session with this skill installed

    Design a new set of endpoints for an e-commerce order management system. I need to handle order creation, status updates, and listing orders for a customer with pagination.

    • Read your context and instructions
    • Compiled the rest api design

    I have mapped out the order management resources. The design follows plural noun conventions, uses RFC 9457 for errors, and includes idempotency for order placement.

    Order Management API Design

    MethodPathPurposeAuthSuccessErrors
    POST/ordersPlace a new orderorders:write201400, 401, 409
    GET/customers/{id}/ordersList customer ordersorders:read200401, 404
    GET/orders/{id}Get order detailsorders:read200401, 404
    PATCH/orders/{id}Partial update (e.g. status)orders:write200400, 401, 404, 412
    POST/orders/{id}:cancelCancel an orderorders:write200401, 404, 409
    openapi: 3.1.0
    info:
      title: Order Management API
      version: 1.0.0
    paths:
      /orders:
        post:
          summary: Place order
          parameters:
            - name: Idempotency-Key
              in: header
              required: true
              schema:
                type: string
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/OrderInput'
          responses:
            '201':
              description: Created
              headers:
                Location:
                  schema:
                    type: string
            '400':
              $ref: '#/components/responses/Error'
    components:
      schemas:
        OrderInput:
          type: object
          properties:
            customerId:
              type: string
            items:
              type: array
              items:
                $ref: '#/components/schemas/LineItem'
        LineItem:
          type: object
          properties:
            productId:
              type: string
            quantity:
              type: integer
      responses:
        Error:
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer }
                  detail: { type: string }
    

    Next steps

    1. Implement the Idempotency-Key storage logic with a 24-hour TTL.
    2. Configure your API gateway to validate the orders:write scope for POST/PATCH operations.
    3. Define the HMAC signing secret for the order.created webhook notification.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    Building APIs that developers actually enjoy using is harder than it looks. Inconsistent naming, vague error codes, and poor pagination logic lead to integration friction and support tickets. This skill enforces strict REST conventions to ensure your API is predictable, scalable, and standards-compliant.

    What it does

    • Standardizes resource naming using plural nouns and consistent casing across all endpoints.
    • Enforces HTTP semantics by mapping actions to correct methods like PUT for idempotency and PATCH for partial updates.
    • Implements RFC 9457 errors to provide machine-readable, consistent error responses for all failure states.
    • Architects scalable patterns including cursor-based pagination, ETag-based concurrency control, and idempotency keys.
    • Generates OpenAPI 3.1 specs complete with schemas, real-world examples, and security definitions.

    How it works

    1. Analyze requirements by mapping out resources, relationships, and specific business use cases.
    2. Draft design starting with an endpoints table covering paths, methods, and expected status codes.
    3. Generate documentation in OpenAPI 3.1 YAML format including detailed request/response objects.
    4. Audit and refine against a comprehensive checklist to catch breaking changes or security gaps like IDOR.

    Frameworks & tools

    This skill produces standard OpenAPI 3.1 YAML compatible with Swagger UI, Redoc, and Postman. It follows industry standards like RFC 9457 for errors, ISO 8601 for time, and OAuth2/OIDC for authentication patterns.

    Why this beats prompting it yourself

    Most LLMs mix different API styles or forget edge cases like 412 Precondition Failed for concurrency. This skill applies a rigid architectural framework that guarantees consistency in error handling, pagination, and idempotency across your entire service.

    Use cases

    • Design a new microservice API from scratch with full OpenAPI documentation.
    • Review existing endpoints to identify non-standard status codes or naming.
    • Add complex features like cursor pagination or HMAC-signed webhooks to an existing spec.
    • Refactor a legacy API to follow modern REST best practices and RFC 9457.

    Known limitations

    Does not support SOAP or gRPC. Focuses on REST/HTTP patterns only. Requires manual implementation of the generated logic in your specific backend language.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for APIs & Backend.

    Focuses strictly on REST/HTTP; no support for SOAP or gRPC. Does not generate server-side implementation code, only specifications and design documentation.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    5.0
    1 review
    5
    1
    4
    0
    3
    0
    2
    0
    1
    0

    This skill has been used 7 times.

    Trust & safety

    Security scan

    Security scan passed 7 days ago

    • Free with an Agensi account

    Permissions

    Network Access
    Listed7 days ago
    Updated6 days ago

    What's inside

    Frequently Asked Questions

    The skill generates standard OpenAPI 3.1 YAML files, which are universally compatible with tools like Swagger UI, Redocly, Postman, and most backend framework generators.

    Unlike generic prompts, this skill enforces a rigid architectural framework including RFC 9457 error standards and ETag-based concurrency, ensuring your API remains consistent across dozens of endpoints.

    While the skill handles the architectural design and OpenAPI documentation, you will still need to manually implement the business logic in your chosen programming language (e.g., Node.js, Python, or Go).

    Yes, you can provide an existing spec or endpoint list, and the skill will audit it for REST violations, non-standard status codes, and security gaps like IDOR.

    The skill is optimized for RESTful architectures over HTTP; it does not support SOAP, gRPC, or GraphQL design patterns.

    New in APIs & Backend

    Free