api and interface design

    1

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

    Free

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+22 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.

    How to use

    Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill passes our trust checks below.

    Security scanned

    Passed our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scanned

    Verified clean 2 days ago

    • Free to download with an account

    Listed2 days ago

    What's inside

    Frequently Asked Questions