skills.rest
bm629
bm629COMMUNITY
Explore all skills by this author →
GitHub

rest-api-design

Designs REST/HTTP API surfaces and expresses them as OpenAPI 3.1 contracts.

1|1|Updated May 24, 2026
Search Tags:#api design#rest api#pagination#api versioning#http status codes#rfc 9457#openapi 3.1
One-click install
npx skills add https://github.com/bm629/agent-skills --skill rest-api-design-bm629
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: rest-api-design
Source: https://github.com/bm629/agent-skills/tree/main/skills/rest-api-design
Command: npx skills add https://github.com/bm629/agent-skills --skill rest-api-design-bm629

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Designing a REST API involves dozens of interlocking decisions — resource naming, HTTP methods, status codes, error formats, pagination, versioning, auth, and rate limiting — and inconsistent choices produce APIs that are hard to consume and evolve. This Skill applies opinionated, standards-based defaults (RFC 9110, RFC 9457, OpenAPI 3.1) so every design decision is coherent and the result maps directly onto a machine-readable contract. ## Core Features & Use Cases - Resource and method modeling: Turns domain nouns into plural, consistently nested URL resources and assigns the correct HTTP method with idempotency semantics (PUT vs PATCH, Idempotency-Key for retried POSTs). - Status codes and one error model: Picks the right status per outcome (400 vs 422, 401 vs 403, 409) and standardizes all errors on RFC 9457 application/problem+json with an errors array for field-level validation. - Contract patterns: Defines a single success/pagination envelope (cursor/keyset by default, offset for small stable datasets), URL-path major versioning with Deprecation/Sunset headers, Bearer/API-key auth, and 429 + Retry-After rate limiting. - OpenAPI 3.1 output: Maps the finished design onto a complete OpenAPI 3.1 document with $ref-reused schemas, responses, parameters, and security schemes. - Use Case: Given domain entities like orders and customers, produce the full endpoint map, status-code table, problem+json error model, cursor-paginated list envelope, and a worked OpenAPI 3.1 contract ready for a FastAPI engineer to implement. ## Quick Start Use rest-api-design to design the REST API for my orders and customers domain and produce the OpenAPI 3.1 contract.

Frequently Asked Questions about rest-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a REST API and generate an OpenAPI contract?▼

Model resources as plural nouns, assign HTTP methods per RFC 9110 semantics, pick a status code per outcome, define one RFC 9457 problem+json error model, and shape a paginated success envelope. The design then maps directly onto an OpenAPI 3.1 document with paths, components, and securitySchemes.

What is the difference between 400 and 422 status codes?▼

400 Bad Request means the server could not parse the request at all, such as malformed JSON. 422 Unprocessable Content means the request parsed fine but failed semantic or business validation. New APIs should default to 422 for validation failures and 400 for parse failures.

Should I use cursor or offset pagination for my API?▼

Cursor (keyset) pagination is the default for large or frequently changing data because it is stable under concurrent writes and constant-time on deep pages. Use offset pagination only for small, stable datasets that need random page jumps or a total count.

Does OpenAPI 3.1 support the nullable keyword?▼

No. OpenAPI 3.1 aligns with JSON Schema 2020-12 and removed the 3.0 nullable keyword. Express nullability as a type union such as type: ["string", "null"]; a stray nullable: true in a 3.1 document is silently ignored.

When should I not use this REST design skill?▼

Do not use it to write FastAPI handler or router code, model Pydantic schemas in depth, or design GraphQL and gRPC surfaces. It owns the design decisions and contract only; framework implementation belongs to the fastapi and pydantic-v2 skills.

Related Skills

Explore More Software Engineering Skills→
eencinasqeencinasq

domain-language-extraction

Extracts domain terminology from business documents into a ubiquitous language dictionary.

Community
Intermediate
JasonLoJasonLo

ss-fastapi-expert

Build asynchronous Python APIs with FastAPI, Pydantic V2, and async SQLAlchemy.

Community
Advanced
OpenLaborOpenLabor
4

API Design

Design RESTful APIs with OpenAPI documentation, versioning, pagination, and error codes.

Official
Intermediate
DazlarusDazlarus

grpc

Designs gRPC services, protobuf schemas, and streaming RPC implementations.

Community
Intermediate