Compatible with Cursor, Claude Code, Cline, Roo Code, Antigravity

Backward-Compatible RESTful API Design & OpenAPI Spec

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

APIRESTOpenAPIArchitectureBackend

v1.1.0 · Updated 2026-08

Skill Objective

Design enterprise-grade, backward-compatible RESTful API contracts compliant with OpenAPI 3.1, RFC 7807 problem details, and cursor pagination.

Execution Workflow Procedure

Ordered steps the coding agent executes when performing this skill.

Resource URI Modeling & HTTP Verbs

Model resource-oriented endpoints with plural nouns and appropriate verbs (GET, POST, PUT, PATCH, DELETE).

Enforce Idempotency & Optimistic Locking

Incorporate Idempotency-Key headers for mutation endpoints and ETag/If-Match headers for concurrency control.

Design Cursor-Based Pagination & Filtering

Implement cursor-based pagination tokens for large datasets and standardize query filtering parameters.

Generate OpenAPI 3.1 Specification

Produce complete OpenAPI YAML/JSON definitions with schemas, error models, and example payloads.

Agent Safety Guardrails & Anti-Hallucination Rules

DO NOT introduce breaking field renames or deletions in active API versions.
DO NOT use RPC-style action verbs in endpoint paths (e.g. POST /createOrder).

Expected Output Format

OpenAPI 3.1 spec and example request/response payloads.

📐 OpenAPI 3.1 Specification: Complete schema, routes, and error models.

💡 Example Payloads: Happy path and error response examples.

Domain Verification Checks

REST Semantics: Resource-oriented noun URIs.

RFC 7807 Errors: Standard problem details schemas.

Cursor Pagination: Stable dataset navigation.

Example Agent Invocations

"Design a backward-compatible RESTful API contract for our team invitation and role assignment system."

"Review this proposed payment webhook API for idempotency and pagination design."

Install / Configure This Skill

# Place in .cursorrules or create .cursor/rules/backward-compatible-rest-api-design.mdc
# Trigger: Whenever you perform backward-compatible restful api design & openapi spec

---
name: backward-compatible-rest-api-design
description: Design RESTful API contracts adhering to OpenAPI 3.1, RFC 7807 errors, cursor pagination, and idempotency.
version: 1.1.0
compatibility: [Cursor, Claude Code, Cline, Roo Code, Antigravity]
---

# Backward-Compatible RESTful API Design & OpenAPI Spec

## Objective
Design scalable, backward-compatible REST APIs with standardized error handling and idempotency guarantees.

## Workflow
1. **Resource Modeling**: Use plural nouns and appropriate HTTP verbs (POST /orders instead of /createOrder).
2. **Idempotency & Concurrency**: Support `Idempotency-Key` headers and `ETag` optimistic locking.
3. **Cursor Pagination**: Provide opaque cursor tokens for stable high-volume pagination.
4. **OpenAPI Output**: Deliver a complete OpenAPI 3.1 YAML/JSON contract.

Complementary Agent Prompt

Need a quick one-time prompt for chat?

Try the RESTful API Design & Backward Compatibility Review — a lightweight version designed for 1-click copying directly into Claude, ChatGPT, or Cursor chat.

View Prompt