# Design API Contracts

> Design or review API contracts for HTTP/REST services and agent-facing endpoints. Use when creating routes, endpoints, status codes, pagination, error responses, versioning, OpenAPI specs, idempotency, or API behavior for AI clients. Produces a clear API contract and review checklist.

- Skill: `ariaxhan/design-api-contracts` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ariaxhan/design-api-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ariaxhan/design-api-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ariaxhan (https://skillmd.com/u/ariaxhan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ariaxhan/design-api-contracts

---


# Design API Contracts

APIs are contracts. Resources are nouns, methods are verbs, and errors must be machine-readable.

## 1. Define resources and operations

Name resources as plural nouns:

- `/users`
- `/team-members`
- `/orders/{id}/items`

Use HTTP methods for actions:

- `GET` read
- `POST` create or trigger a deliberate action
- `PUT` replace
- `PATCH` partial update
- `DELETE` remove

Use action endpoints sparingly, like `POST /orders/{id}/cancel`.

## 2. Specify status codes

Pick the semantically correct code for every outcome: `2xx` success, `4xx` caller error,
`5xx` server/dependency failure. Never return `200` for errors. Full code table:
[`reference/http-conventions.md`](./reference/http-conventions.md).

## 3. Validate request and response shape

Define request params, request body schema, success response, error response, and the
pagination shape for list endpoints. Use a consistent success envelope and stable,
machine-readable error codes, never a bare string error. The envelope and error templates
live in [`reference/http-conventions.md`](./reference/http-conventions.md).

## 4. Add pagination and idempotency

Every list endpoint needs pagination.

Use cursor pagination for feeds or large datasets. Use page/per-page for admin views where jumping matters.

State-changing endpoints that may be retried need idempotency keys, especially payments, orders, imports, and agent-called APIs.

## 5. Version deliberately

Document what is breaking:

- Removing/renaming fields
- Changing types
- Changing URL structure
- Changing required fields

Add a new version for breaking changes. Additive optional fields usually do not require one.

## 6. Make it agent-friendly when needed

For AI/automation clients:

- Publish an OpenAPI or schema-first contract.
- Document retry behavior.
- Use distinct error codes per failure mode.
- Return opaque cursors, not math the agent must derive.
- Make state-changing operations idempotent.

## 7. Review checklist

Before implementation or merge, walk the contract against the review checklist in
[`reference/http-conventions.md`](./reference/http-conventions.md): no verbs in resource
URLs, no unbounded list endpoints, no bare-string or `200` errors, validation before
processing, auth named, breaking changes versioned, agent endpoints document retry safety.