- Home
- Skills
- APIs & Backend
- API and Interface Design Patterns
More screenshots
Works with the AI Agents you already use
API and Interface Design Patterns
Design APIs and module boundaries that survive real callers: consumer-first contracts, one error shape, safe retries, and a change policy that never strands the people depending on you.
$5
API and Interface Design Patterns
Example session with this skill installed
We're about to build the API for an appointment-booking service. Web app first, a mobile app next quarter, and maybe partner integrations later. Design the contract before we write any code.
- Read your context and instructions
- Compiled the api and interface
CONSUMERS — Web app (ours, ships first), mobile app (ours, next quarter, flaky networks), possible partners (external, uncontrolled — so design public-grade from day one). Change forecast: services and staff will be added; slot naming may change; payments arrive later.
VOCABULARY (one name each) — appointment, slot, service, staffMember, customer. The business also says "booking" — picked once: resource is appointment; "booking" appears nowhere in paths, fields, or errors.
CONTRACT (drafted before any handler):
- POST /appointments — CreateAppointment { serviceId, staffMemberId, slotStart, customerNote? } → Appointment { id, …, status, createdAt }. Input and output are different types; server fields never appear in the request.
- GET /appointments?from&to — always a page: { data, page, pageSize, total }, even though a day holds ~40 rows today.
- GET /appointments/:id — 404 in the standard envelope when absent.
- POST /appointments/:id/cancel — safe to call twice; second call returns the already-cancelled appointment.
ERRORS — one envelope everywhere: { error: { code, message, details? } }. Codes like appointment.slot_taken (409) and appointment.not_found (404); 400 bad input, 401/403 auth, 422 well-formed but invalid, 500 with no internals leaked.
RETRY SAFETY — create accepts a client-generated Idempotency-Key, one key per booking intent, claimed by unique insert. A mobile double-submit on a bad connection creates one appointment; the same key with a different body fails loudly as a caller bug.
CHANGE POLICY — add-don't-alter, dual-support for renames (return both fields for two release cycles, then drop after the announced window). Classified now: adding payments later = new endpoints (safe); renaming slot → timeSlot = breaking, handled by dual return, no version bump.
SCORE — consumer clarity 2, vocabulary 2, error consistency 2, pagination 2, retry safety 2, change policy 2 = 12/12. Gate: green to implement.
Connects securely to your tools. The creator never sees your data.
About this skill
An interface is a promise you will be asked to keep for years, and this skill walks the full life of one: conceived, shipped, depended on, and changed under load. Phase 1 names the consumers and fixes the vocabulary before any contract is drafted — one name per concept, everywhere, because naming drift is the cheapest bug to introduce and the most expensive to fix. Phase 2 makes the shipped contract predictable: a single error envelope with stable machine-readable codes and one status mapping, plural-noun paths, pagination on every list from day one, and separate input and output types so callers never guess which fields they may send. Phase 3 guards the edges once callers exist: validation only where outside data enters, branded identifier types, and a deprecation path planned at design time instead of under pressure. Phase 4 is the change discipline most teams lack: a classification table that labels every proposed change safe or breaking (including the sneaky ones, like tightened validation and changed ordering), plus a complete retry-safety protocol covering idempotency keys, atomic key claiming, and what a concurrent retry should receive. A six-dimension scorecard rates a draft contract before implementation starts, an edge-case section covers escaping internal APIs, strict-shape consumers, generated clients, and webhook payloads, and a worked example follows one booking API through three months of changes without a version bump. The same rules are applied to module boundaries and component props, because the discipline is one habit, not two.
- It designs and reviews contracts; it does not generate the implementation or an OpenAPI file for you — your stack's tooling does that from the contract.
- Retry-safety advice assumes you control the server side; against a third party's API you can only apply the caller-side half.
- The scorecard is calibrated judgment, not a certification; regulated interfaces may need formal review on top.
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 24 days ago
Permissions
No special permissions declared or detected