skills.rest
ValenBorras
ValenBorrasCOMMUNITY
Explore all skills by this author →
𝕏@ValenBorras_GitHub

api-design

Design consistent REST APIs with standard naming, status codes, pagination, and versioning.

1|Updated Mar 18, 2026
Search Tags:#design#versioning#api#rest#pagination#naming
One-click install
npx skills add https://github.com/ValenBorras/upscribe --skill api-design-valenborras
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/ValenBorras/upscribe/tree/main/.github/skills/api-design
Command: npx skills add https://github.com/ValenBorras/upscribe --skill api-design-valenborras

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Inconsistent API designs create integration friction, poor developer experience, and versioning chaos. This section explains how standardized API design patterns solve these issues by providing rules for resource naming, HTTP methods, status codes, pagination, filtering, and versioning.

Core Features & Use Cases

  • Resource naming conventions (plural nouns, kebab-case) to produce intuitive endpoints such as /api/v1/users and /api/v1/users/:id
  • Standard HTTP status codes and structured error responses to improve client handling and debuggability
  • Pagination and filtering patterns to support scalable data access and flexible queries
  • Versioning strategies to manage breaking changes gracefully and minimize disruption
  • Governance guidance for public, partner, and internal APIs to maintain consistency across services
  • Example workflows: designing endpoints with clear ownership and predictable contracts

Quick Start

Define your first API contract by applying the naming, versioning, and status-code rules outlined above.

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 endpoints for resources?▼

Design consistent REST API endpoints by applying standard naming conventions like plural nouns and kebab-case (e.g., /api/v1/users) to produce intuitive resource paths. This ensures predictable contracts and improves client integration.

What are the best practices for REST API versioning and breaking changes?▼

REST API versioning manages breaking changes gracefully by applying a practical versioning approach in the URI path, such as /api/v1/. This strategy minimizes disruption for existing clients while allowing the API contract to evolve.

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

REST API error responses should use standard HTTP status codes alongside structured error formats to improve client handling and debuggability. This standardized approach allows clients to programmatically manage errors and trace issues effectively.

What pagination and filtering patterns work best for scalable REST API data access?▼

Scalable REST API data access relies on standard pagination and filtering patterns to support flexible queries. These patterns prevent excessive payload sizes and ensure efficient data retrieval across large resource collections.

Does this REST API design approach apply to internal, partner, and public APIs?▼

Yes, this REST API design approach includes governance guidance for maintaining consistency across public, partner, and internal APIs. It ensures clear ownership and predictable contracts regardless of the API's exposure level.

Related Skills

Explore More Software Engineering Skills→
alexsandrocruzalexsandrocruz

api-design-principles

Design REST APIs with resource-oriented naming, HTTP methods, status codes, and versioning.

Community
Basic
curiositechcuriositech
181

openapi-spec-writer

Generate OpenAPI 3.0/3.1 YAML or JSON specifications for REST APIs.

Official
Advanced
cenjiecenjie

api-security-hardening

Secure REST APIs with authentication, rate limiting, CORS, and input validation.

Community
Advanced
Camilo8902Camilo8902

rest-to-graphql-migrator

Migrate REST APIs to GraphQL incrementally using schema stitching and REST data source wrappers.

Community
Advanced