skills.rest
randalmurphal
randalmurphalCOMMUNITY
Explore all skills by this author →
GitHub

api-design-patterns

Standardize REST API design with versioning, pagination, RFC 7807 errors, and OpenAPI documentation.

Updated Sep 8, 2025
Search Tags:#versioning#openapi#rest#pagination#api-design
One-click install
npx skills add https://github.com/randalmurphal/claude-config --skill api-design-patterns-randalmurphal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-patterns
Source: https://github.com/randalmurphal/claude-config/tree/main/skills/api-design-patterns
Command: npx skills add https://github.com/randalmurphal/claude-config --skill api-design-patterns-randalmurphal

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST API design patterns including versioning strategies (URL, header, content negotiation), pagination (offset, cursor, keyset), filtering and sorting, error response formats (RFC 7807), authentication (JWT, OAuth 2.0, API keys), rate limiting, and OpenAPI specification. Use when designing APIs, documenting endpoints, implementing authentication, standardizing error responses, or reviewing API implementations.

Core Features & Use Cases

  • Resource-based Design: Nouns over actions; consistent URL structure.
  • Versioning & Errors: Version schemes and RFC 7807 error formats.
  • Authentication & Security: JWT/OAuth patterns.
  • Documentation: OpenAPI integration and examples.

Quick Start

Start with a minimal OpenAPI spec and a versioned endpoint, then add error formats and pagination strategies.

Frequently Asked Questions about api-design-patterns

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

FAQPage Schema
How do I version a REST API without breaking existing clients?▼

REST API versioning strategies include URL paths (/v1/, /v2/), request headers, and content negotiation. URL versioning is most explicit and client-friendly; choose based on your API's stability requirements and whether you need to support multiple versions simultaneously.

What's the best way to handle pagination in REST APIs?▼

Pagination methods include offset-based, cursor-based, and keyset pagination. Offset works for small datasets; cursor and keyset handle large or frequently-updated data better by reducing inconsistency and improving performance.

How should I format error responses in REST APIs?▼

RFC 7807 defines a standardized problem detail format for HTTP errors, improving client error handling. It includes status, type, title, and detail fields, enabling consistent error parsing across API consumers.

How do I document REST API endpoints effectively?▼

OpenAPI specification provides machine-readable, standardized API documentation. It enables automatic client generation, interactive API explorers, and ensures endpoint contracts are clear to developers integrating your API.

What authentication patterns work best for REST APIs?▼

Common patterns include JWT tokens, OAuth 2.0 flows, and API keys. JWT and OAuth 2.0 suit delegated access and third-party integrations; API keys work for simpler, first-party scenarios with lower security overhead.

Related Skills

Explore More Software Engineering Skills→
armanzeroeightarmanzeroeight
29

rest-api-designer

Design RESTful API endpoints with resource models, HTTP methods, and URL structures.

Community
Intermediate
DexploarerDexploarer
7

api-gateway-configurator

Configure API gateways including Kong with JWT authentication and rate limiting for microservices.

Community
Advanced
ConnectiveTCSConnectiveTCS

api-expert

Design secure APIs with OpenAPI 3.1, OAuth2/JWT, and rate limiting.

Community
Advanced
skinred78skinred78
1

backend-development

Design production-ready backends with REST, GraphQL, and gRPC APIs.

Community
Advanced