Ryan Mitchell·
Got a full REST spec for our payments API - idempotency keys, RFC 7807 errors, cursor paging, the lot
Creates a production-ready REST API specification with resource naming, HTTP method conventions, pagination strategies, versioning, and OpenAPI documentation.
REST API Design & Standards
Act as an API Design architect and creator of API standards for a Fortune 500 company. Design a complete REST API for the following domain.
**Domain**: {{domain}} (e.g., payment processing, content management, IoT device management)
**Consumers**: {{consumers}} (internal services, mobile apps, third-party developers, partner integrations)
**Scale**: {{scale}} (requests per second, peak traffic patterns)
**Security Requirements**: {{security_requirements}} (auth methods, PII handling, compliance needs)
Deliver the following:
1. **Resource Model** - Complete list of resources with URI templates (/v1/users/{userId}/orders/{orderId})
2. **HTTP Method Semantics** - Which methods (GET/POST/PUT/PATCH/DELETE) apply to each resource with idempotency guarantees
3. **Request/Response Schemas** - JSON schema for every endpoint including field types, validation rules, and examples
4. **Status Code Strategy** - Precise status codes for every scenario (200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500, 503)
5. **Error Response Format** - RFC 7807 Problem Details standard or equivalent with error codes, messages, and remediation hints
6. **Pagination Strategy** - Cursor-based vs offset-based with implementation for each list endpoint
7. **Filtering, Sorting, Searching** - Query parameter conventions (filter[field]=value, sort=-created_at, q=search_term)
8. **Versioning Strategy** - URL vs header vs content-type versioning with deprecation policy
9. **Rate Limiting Headers** - X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After
10. **HATEOAS Links** - Self, next, prev, related link patterns if applicable
11. **OpenAPI 3.1 Specification** - Complete OAS YAML for all endpoints
12. **SDK Generation Plan** - Target languages and code generation strategy
Every endpoint must include a complete curl example request and response.
Ergebnisse
Designed the REST surface for a **payment-processing** domain (third-party developers, ~3k RPS peak, PCI-DSS + idempotency required). Core decisions below; full OpenAPI YAML attached separately.
**Resource model**
```
/v1/payment-intents
/v1/payment-intents/{intentId}
/v1/payment-intents/{intentId}/capture # POST, action sub-resource
/v1/customers/{customerId}/payment-methods
```
**POST /v1/payment-intents** — create is idempotent via header, not body:
```bash
curl -X POST https://api.acme.dev/v1/payment-intents \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: a1f9-3c20" \
-d '{ "amount": 4999, "currency": "EUR", "customer": "cus_812" }'
```
```json
{ "id": "pi_9KdZ", "status": "requires_capture", "amount": 4999,
"_links": { "self": "/v1/payment-intents/pi_9KdZ",
"capture": "/v1/payment-intents/pi_9KdZ/capture" } }
```
**Status codes that matter:** `201` create, `409` on idempotency-key reuse with a different body, `422` for a valid-JSON-but-invalid amount, `429` with `Retry-After`. Errors follow RFC 7807:
```json
{ "type": "https://api.acme.dev/errors/card-declined",
"title": "Card declined", "status": 402, "code": "card_declined",
"detail": "Issuer declined the charge.", "instance": "/v1/payment-intents/pi_9KdZ" }
```
**Pagination:** cursor-based (`?limit=20&starting_after=pi_9KdZ`) — offset paging breaks under high write volume. **Versioning:** URL-prefixed `/v1` plus a dated `Acme-Version` header for additive changes; 12-month deprecation via `Sunset` header.
Modell: Claude Opus 4
3 Likes1 SavesScore: 3