Architecture & API Design
Target: Claude 3.7, Cursor, Windsurf, ChatGPT

RESTful API Design & Backward Compatibility Review

Design or review RESTful API contracts for idempotency, pagination, error models, and non-breaking versioning.

APIRESTOpenAPIArchitectureBackend

Interactive Prompt Playground

Customize Template Fields
Live replacement
{{API_SPEC}}
{{CONSUMER_CONTEXT}}
{{VERSIONING_STRATEGY}}
Rendered Prompt (Ready to paste)1622 characters
You are an API Architect and author of enterprise API design guidelines.

Review this proposed REST API contract / OpenAPI spec:

```json
POST /api/createOrder
Request:
{
  "user_id": "123",
  "items": [{ "id": "p1", "qty": 2 }],
  "payment": { "type": "card", "token": "tok_abc" }
}

Response (200 OK):
{
  "status": "success",
  "orderId": "ord_999",
  "total": 49.99
}
```

Domain Context & Target Consumers: Public B2B API consumed by mobile apps and third-party webhooks
Versioning Constraints: URL path versioning (/v1) with non-breaking field additions

Evaluate the API design against world-class REST standards:
1. **Resource URI Modeling & HTTP Methods**:
   - Check noun pluralization, hierarchical nesting, and correct HTTP verb usage (GET, POST, PUT, PATCH, DELETE).
2. **Backward Compatibility & Evolution**:
   - Will these changes break mobile apps or legacy integrations?
   - Are optional vs required fields handled gracefully?
3. **Idempotency & Concurrency Control**:
   - Are mutation operations idempotent with `Idempotency-Key` headers?
   - Is optimistic locking supported via `ETag` / `If-Match` headers?
4. **Pagination, Filtering, & Sorting**:
   - Is cursor-based pagination used for high-volume datasets instead of offset/limit?
   - Are filtering query parameters structured consistently?
5. **Error Format & Problem Details**:
   - Are errors compliant with RFC 7807 (Problem Details for HTTP APIs)?

Provide your output:
- 📑 **Design Critique & Breaking Change Warnings**
- 📐 **Recommended OpenAPI / JSON Schema Specification**
- 💡 **Example Request / Response Payloads with Edge Cases**

How to Use This Prompt

  1. Paste your planned API endpoints, request bodies, and response schemas.
  2. State your client requirements (e.g. mobile apps, third-party developers).
  3. Get a standardized, backward-compatible API specification.

Engineering Tips & Best Practices

  • Never remove or rename response fields in active API versions; mark them deprecated and introduce additive fields.

What This Prompt Inspects

Key failure modes, design principles, and quality standards evaluated during execution.

RESTful Semantics

Replaces RPC-style action URLs (/createOrder) with resource-oriented endpoints (POST /orders).

RFC 7807 Errors

Standardizes error payloads with type, title, status, detail, and instance fields.

Cursor Pagination

Provides cursor-based pagination tokens for stable list iteration.

SprintKit Workflow Integrations

Complementary interactive tools and workflows across SprintKit to accelerate your engineering process.

Related Prompts

Explore related developer prompts in this workflow domain.

All Prompts

Technical Design Document (RFC) Generator

Generate thorough, engineering-ready Request for Comments (RFC) and Architecture Decision Records (ADRs).

ArchitectureRFCADRPlanning+1
3 variablesCustomize prompt

Database Schema & Relational Indexing Strategy

Design production PostgreSQL schemas with composite indexes, foreign key strategies, and partitioning.

PostgreSQLSQLDatabaseIndexing+1
4 variablesCustomize prompt

Spring Boot REST Service & JPA Code Review

Deep code review for Spring Boot services examining transaction boundaries, JPA N+1 queries, concurrency, and validation.

JavaSpring BootJPAHibernate+2
4 variablesCustomize prompt