api and interface design

    1

    Design stable, predictable APIs and module boundaries using contract-first principles and robust idempotency patterns.

    Free

    1 useSecurity scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    api and interface design

    Example session with this skill installed

    Design a REST API endpoint for creating a new project. Include the TypeScript interface, error handling, and idempotency logic.

    • Read your context and instructions
    • Compiled the api and interface

    I have designed the project creation interface following contract-first principles and robust idempotency patterns.

    Project Creation API Design

    Interface Definition

    // Input: Provided by the client
    interface CreateProjectInput {
      name: string;
      description?: string;
      visibility: 'PUBLIC' | 'PRIVATE';
      teamId: string;
    }
    
    // Output: System-generated fields included
    interface Project {
      id: string & { readonly __brand: 'ProjectId' };
      name: string;
      description: string | null;
      visibility: 'PUBLIC' | 'PRIVATE';
      teamId: string;
      createdAt: Date;
      updatedAt: Date;
      status: 'ACTIVE' | 'ARCHIVED';
    }
    

    API Endpoint & Error Handling

    POST /api/projects
    Headers: Idempotency-Key: <unique-uuid>

    Status CodeError CodeDescription
    201 Created-Project created successfully
    409 ConflictIDEMPOTENCY_IN_PROGRESSA request with this key is already being processed
    422 UnprocessableVALIDATION_ERRORInvalid input or key reused with different payload

    Idempotency Logic

    The implementation must use an atomic claim to prevent race conditions:

    try {
      // Atomic insert to claim the key
      await db.insert('idempotency_keys', {
        key: idempotencyKey,
        request_hash: hash(req.body),
        status: 'started'
      });
    } catch (e) {
      if (isUniqueViolation(e)) {
        const existing = await db.find('idempotency_keys', idempotencyKey);
        if (existing.request_hash !== hash(req.body)) {
          return error(422, 'IDEMPOTENCY_KEY_REUSE_WITH_DIFFERENT_PAYLOAD');
        }
        return error(409, 'REQUEST_IN_PROGRESS');
      }
      throw e;
    }
    

    Next steps

    1. Implement the CreateProjectSchema using Zod for boundary validation.
    2. Set a 24-hour TTL on the idempotency_keys table.
    3. Add the ProjectId branded type to your global types file.

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

    About this skill

    Interfaces are the most expensive things to change once they are live. This skill helps you design stable, predictable APIs and module boundaries that resist breaking changes and prevent misuse. It provides concrete patterns for REST, GraphQL, and TypeScript interfaces, grounded in principles like Hyrum's Law and the One-Version Rule.

    What it does

    • Enforces contract-first design by requiring interface definitions before implementation to prevent tight coupling.
    • Standardizes error semantics using structured machine-readable codes and consistent HTTP status mapping.
    • Secures system boundaries by implementing validation at the edges (API routes, forms, and third-party responses) while trusting internal types.
    • Hardens state-changing operations with rigorous idempotency patterns, including atomic key claims and payload guarding to prevent race conditions.
    • Optimizes resource design through specific conventions for RESTful naming, pagination, and partial updates using PATCH.

    How it works

    1. Define the contract by drafting TypeScript interfaces or API schemas for inputs and outputs.
    2. Apply design principles such as Hyrum's Law to ensure implementation details do not leak into the public surface.
    3. Audit against red flags like verbs in URLs, inconsistent error shapes, or non-atomic idempotency checks.

    Frameworks & tools

    TypeScript, REST, GraphQL, and Zod-style schema validation. Applicable to any backend or frontend stack where code modules interact.

    Why this beats prompting it yourself

    Generic prompts often ignore the nuance of Hyrum's Law or provide flawed idempotency logic that fails under race conditions. This skill provides production-grade patterns that specifically solve the diamond dependency problem and correlated retry storms.

    Use cases

    • Drafting a new microservice API that needs to support multiple frontend consumers.
    • Refactoring a legacy module boundary to improve type safety and developer experience.
    • Implementing safe payment or transaction processing using robust idempotency keys.
    • Designing a public-facing SDK where backward compatibility is a hard requirement.

    Known limitations

    Does not provide implementation code for specific database drivers or web frameworks. Focuses on the interface layer and logic patterns rather than infrastructure setup.

    Focuses on design patterns and logic rather than infrastructure code. Does not provide specific database drivers or framework-specific boilerplate.

    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 any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    1 use

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 1 month ago

    • Free with an Agensi account

    Permissions

    No special permissions declared or detected

    Listed1 month ago

    What's inside

    Frequently Asked Questions

    This skill focuses on the architectural 'contract' layer, providing production-grade patterns for idempotency, error handling, and resource naming that prevent breaking changes and race conditions. Unlike generic prompts, it applies specific principles like Hyrum’s Law to ensure your interfaces remain stable even as your implementation evolves.

    While the skill uses TypeScript and Zod-style schemas as its primary design language, the architectural principles are language-agnostic. You can apply the resulting interface designs and idempotency logic to any backend stack, including Node.js, Go, Python, or Java.

    The skill provides robust, atomic idempotency patterns designed to handle concurrent requests and retry storms safely. It guides you through implementing payload guarding and unique key claims to ensure that state-changing operations, like payments, are never executed twice.

    You receive a specialized set of design protocols, schema templates for REST and GraphQL, and an auditing framework to check for common interface 'red flags.' It includes specific strategies for versioning and backward compatibility to help you avoid the 'diamond dependency' problem.

    This skill is a design and architecture tool rather than a code generator for infrastructure. It provides the logic, structure, and validation patterns for your API, but you will still need to connect these designs to your specific database drivers or web framework of choice.

    New in APIs & Backend