skills.rest
beratcelik1
beratcelik1COMMUNITY
Explore all skills by this author →
Website𝕏@beratcelik0GitHub

api-design

Define REST API conventions for resource naming, HTTP methods, status codes, pagination, and error responses.

1|Updated Mar 5, 2026
Search Tags:#versioning#openapi#rest#error-handling#rate-limiting#pagination#api-design
One-click install
npx skills add https://github.com/beratcelik1/compound-claude --skill api-design-beratcelik1
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/beratcelik1/compound-claude/tree/main/skills/api-design
Command: npx skills add https://github.com/beratcelik1/compound-claude --skill api-design-beratcelik1

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST APIs are often inconsistent, ambiguous, and hard for clients to use reliably because of poor resource naming, incorrect status code usage, missing pagination, unclear error formats, and ad-hoc versioning. This Skill captures conventions and concrete patterns to make APIs predictable, debuggable, and safe for public or partner consumption.

Core Features & Use Cases

  • Resource and URL conventions: guidance on nouns, pluralization, kebab-case, and sub-resources to keep endpoints intuitive.
  • HTTP semantics and status codes: mappings for success, client, and server errors and examples of correct usage.
  • Pagination, filtering, and versioning: recommendations for cursor vs offset pagination, filter/query formats, and URL or header-based versioning strategies.
  • Error and response schemas: standardized error envelopes, field-level validation errors, and examples for common frameworks (TypeScript, Django, Go).
  • Use Case: Use these patterns to design a new public users endpoint, add cursor pagination to a feed API, or standardize error responses across microservices.

Quick Start

Use the api-design skill to review and standardize the new /api/v1/orders endpoint for pagination, filtering, and error responses.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design consistent REST API resource naming and URL conventions?▼

REST API resource naming uses nouns, pluralization, kebab-case, and sub-resources to keep endpoints intuitive. Applying these URL conventions ensures your API interfaces remain predictable and easy for clients to consume reliably across web and mobile services.

What are the best REST API pagination and filtering strategies for large datasets?▼

REST API pagination and filtering strategies include comparing cursor versus offset pagination and defining standard query formats. Choosing the right approach prevents performance degradation and ensures stable data retrieval for feed endpoints and large dataset queries.

How should REST API error responses and status codes be structured?▼

REST API error responses should use standardized error envelopes, field-level validation errors, and correct HTTP status code mappings for client and server errors. Structuring errors this way makes APIs debuggable and safe for public or partner consumption.

What is the best way to handle REST API versioning for production endpoints?▼

REST API versioning involves applying URL or header-based versioning strategies compatible with OpenAPI. Implementing strict versioning rules prevents breaking changes and maintains predictable endpoint behavior for public and internal web services.

Can I use these REST API design patterns with frameworks like Django, Go, and TypeScript?▼

REST API design patterns provide concrete conventions and example response envelopes compatible with common frameworks including TypeScript, Django, and Go. These patterns apply directly to backend engineers creating or reviewing public and internal REST endpoints.

When do I need rate limiting in my REST API design?▼

Rate limiting is needed in REST API design to protect public and partner endpoints from abuse and ensure safe consumption. Applying rate limiting conventions alongside authentication scenarios keeps your web and mobile services stable under heavy traffic.

Related Skills

Explore More Software Engineering Skills→
rizwan2004csrizwan2004cs
1

api-design

Design REST API conventions and OpenAPI documentation for backend services.

Community
Intermediate
tsunami28tsunami28

elaboration-upsert-api-contract

Create OpenAPI 3.x YAML contracts from feature requirements and implementation slices.

Community
Advanced
hwatkinshwatkins

api-design

Designs Phoenix-centric REST APIs with resource-based patterns and OpenAPI documentation.

Community
Advanced
yusufcmgyusufcmg
1

api-design-principles

Guide REST and GraphQL API design with patterns and best practices.

Community
Intermediate