- Home
- Skills
- APIs & Backend
- API Design Doctor — Review APIs Before Release
Works with the AI Agents you already use
API Design Doctor — Review APIs Before Release
Review API contracts for security, reliability, compatibility, clear semantics, and developer experience.
$9.99
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
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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 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
File Scopes
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.