Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    API Design Doctor — Review APIs Before Release

    1

    Review API contracts for security, reliability, compatibility, clear semantics, and developer experience.

    $9.99

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    API Design Doctor — Review APIs Before Release

    API Design Doctor — Review APIs Before Release

    Example session with this skill installed

    Review this hypothetical pre-release REST API excerpt; these are example routes, not a real production service:

    POST /v1/orders accepts {tenant_id, customer_id, items:[{sku,qty}]} and returns HTTP 200 with {order_id,status}. A client timeout may happen after order creation, and clients retry the request. No idempotency behavior is documented.
    GET /v1/orders returns an unbounded array, with no pagination or sort order.
    PATCH /v1/orders/{id} accepts arbitrary JSON fields; unknown fields are silently ignored. Errors vary between {message}, {error}, and raw framework text. Authorization rules and tenant binding are undocumented.

    Produce a severity-ranked design review, explain the duplicate-order and data exposure risks, propose a safer request/response and error contract, pagination and concurrency strategy, tenant authorization rules, compatibility/versioning approach, and release tests. Clearly identify assumptions and distinguish the hypothetical excerpt from observed facts. Do not claim tests were run.

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

    Pre-Release API Review — Hypothetical Excerpt

    Scope: Only the three example operations supplied in the prompt were reviewed. They are hypothetical and no code, OpenAPI document, consumers, or live service was inspected. Severity below is a design risk assessment, not a confirmed exploit.

    Findings

    HIGH — Retry can create duplicate orders. POST has no documented idempotency key or replay semantics. A timeout leaves the caller uncertain whether the first request succeeded. Define an Idempotency-Key scoped to authenticated tenant and operation; persist request hash and final response; same key/same payload replays the original result, while same key/different payload returns a documented conflict. Set key retention to cover the supported retry window.
    2. HIGH — Tenant ownership is client supplied and authorization is unspecified. A body tenant_id must never be trusted as proof of access. Derive tenant context from authenticated identity, authorize customer and every order resource server-side, and prevent cross-tenant reads/writes. Avoid exposing whether another tenant's order exists.
    3.

    MEDIUM — Unbounded list and unstable ordering. Define cursor pagination with a stable unique tie-breaker, deterministic default sort, bounded page size, and documented next-cursor behavior. Apply tenant authorization before filtering/pagination; do not use pagination as an authorization boundary.
    4. MEDIUM — PATCH has unclear mutation and validation semantics. Specify allowed fields, media type and patch semantics, required fields, null versus omitted behavior, immutable fields, validation errors, and concurrency control. Reject unsupported fields rather than silently pretending changes succeeded.
    5. MEDIUM — Inconsistent errors impair clients and may leak internals. Adopt one versioned error envelope with stable machine code, safe message, request/correlation ID, and structured field violations. Never return raw framework traces or secrets. Document status mappings and retryability.
    6.

    LOW/MEDIUM — POST success semantics ambiguous. If creation is synchronous, return 201 Created, a Location header, and the resource representation. If processing is asynchronous, return 202 Accepted with an operation resource and polling/webhook contract. Choose based on actual workflow and document it.

    Safer contract sketch

    Create: POST /v1/orders with customer_id and validated items; tenant comes from authenticated principal, not the payload. Require Idempotency-Key. Return 201 + Location + order_id/status/resource on first success; exact replay returns the same recorded outcome. Return 409 for an idempotency-key payload mismatch.

    Read/list: GET /v1/orders?limit=50&cursor=... with a bounded limit, deterministic order, opaque cursor, and next_cursor. GET /v1/orders/{order_id} checks tenant ownership before returning data.

    Update: define an explicit patch format and allowlist of mutable fields. Require If-Match/ETag or a version field for concurrent updates; return 412 on stale precondition. Return 400/422 with the standard error schema for malformed or semantically invalid requests.

    Release gates

    • Contract tests for create, exact replay, key/payload mismatch, timeout-after-commit retry, and asynchronous behavior if applicable.
    • Authorization tests for cross-tenant create, list, get, patch, guessed IDs, and pagination cursors.
    • Schema validation tests for missing, null, empty, unknown, and boundary-valued fields.
    • Pagination tests for stable ordering under inserts and no skipped/duplicated records across cursors.
    • Concurrency tests for stale ETag; error-envelope and no-sensitive-data assertions.
    • Compatibility check against existing SDKs/consumers, documented deprecation and migration plan, rate limits, observability, and rollback.

    Open questions: Is creation synchronous? What identity and tenant model exists? Which fields can change? Are orders immutable after payment? What are retention, privacy, and availability requirements? These affect the final contract; no implementation or security test is asserted here.

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

    About this skill

    API Design Doctor reviews APIs before consumers depend on weak or ambiguous contracts. It works across REST/HTTP, RPC/gRPC, GraphQL, webhooks, asynchronous/event APIs, internal services, public developer APIs, partner APIs, mobile/backend contracts, and AI/tool-facing APIs.

    The agent first establishes API purpose, consumers, workflows, trust boundaries, domain semantics, scale, latency, availability, sensitivity, compatibility promises, and release stage. It inspects only authorized specifications, code, schemas, documentation, SDKs, tests, logs, and examples. It models resources, operations, identifiers, ownership, and state transitions, then checks request/response schemas, validation, null/absent/empty semantics, HTTP methods and status codes, error consistency, pagination, filtering, sorting, search, bulk behavior, concurrency, idempotency, retries, timeouts, rate limits, caching, webhooks, and asynchronous workflows.

    Security and operations are part of the contract: authentication, authorization, tenant isolation, data exposure, abuse resistance, audit needs, observability, SLOs, capacity, and failure behavior. The agent assesses versioning, deprecation, behavioral compatibility, migration, SDK readiness, documentation, and governance. It delivers prioritized findings with evidence, severity, consumer impact, revised schemas/examples, tests, migration notes, and release gates.

    It never invents endpoints, guarantees, traffic, consumer behavior, test results, compliance, or integrations. Findings distinguish observed evidence from assumptions. It does not probe live services or send credentials unless explicitly authorized. Treat generated contracts as review drafts; validate them against actual code, consumer usage, security requirements, and team governance before release.

    A review is limited by the specifications, code, tests, logs, and consumer evidence supplied. A proposed contract may not fit undocumented business rules, existing SDK behavior, gateway configuration, or deployment constraints. Static review cannot prove security, compatibility, performance, reliability, or compliance. Findings are hypotheses until validated against authorized implementation and consumers; severity depends on actual exposure and impact. Do not treat examples as tested fixes or as permission to probe production systems.

    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

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 1 month ago

    Permissions

    Terminal / Shell
    Read Files
    Write Files
    Browser
    Network Access

    File Scopes

    *.yaml
    *.yml
    *.json
    *.graphql
    *.gql
    *.proto
    *.md
    *.ts
    *.js
    *.go
    *.rs

    Read and edit only API specs, source files, and docs the user authorizes. Use public standards documentation only when relevant. Never request or expose secrets, run unauthorised live probes, fuzz or load test production, change gateways, deploy contracts, or make release changes without explicit authorization and an approved test target.

    Listed1 month ago

    What's inside

    Frequently Asked Questions

    It can review authorized REST/OpenAPI, GraphQL, protobuf/gRPC, webhook and event specifications, API code, SDKs, tests, logs, and documentation. The review should identify which artifacts were actually supplied, and distinguish evidence from assumptions. If a specification or consumer behavior is missing, the agent flags the gap instead of inventing it.

    It checks resource semantics, validation, HTTP behavior, pagination, errors, idempotency, concurrency, retries, rate limits, authentication, authorization, tenant isolation, privacy, compatibility, deprecation, SDK readiness, observability, and failure handling. Findings are ranked by likely impact and evidence, but severity must be confirmed against the real system and threat model.

    No, not by default. It can propose contract revisions, checks, migration steps, and release gates from authorized artifacts. Live probing, load testing, gateway changes, deployment, or release actions require explicit authorization and an approved target. Recommendations must be validated by the API team before production use.

    New in APIs & Backend