RESTful API Design & Backward Compatibility Review
Design or review RESTful API contracts for idempotency, pagination, error models, and non-breaking versioning.
Interactive Prompt Playground
{{API_SPEC}}{{CONSUMER_CONTEXT}}{{VERSIONING_STRATEGY}}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
- Paste your planned API endpoints, request bodies, and response schemas.
- State your client requirements (e.g. mobile apps, third-party developers).
- 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.
Technical Design Document (RFC) Generator
Generate thorough, engineering-ready Request for Comments (RFC) and Architecture Decision Records (ADRs).
Database Schema & Relational Indexing Strategy
Design production PostgreSQL schemas with composite indexes, foreign key strategies, and partitioning.
Spring Boot REST Service & JPA Code Review
Deep code review for Spring Boot services examining transaction boundaries, JPA N+1 queries, concurrency, and validation.