api-design

Design REST API contracts with resources, status codes, pagination, and versioning.

Updated Jun 24, 2026

Search Tags:#versioning #error handling #api design #rate limiting #rest #pagination #http status codes

Ready to run

npx skills add https://github.com/mostafa-ismail-2004/codex-plugin --skill api-design-mostafa-ismail-2004

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/mostafa-ismail-2004/codex-plugin/tree/main/skills/api-design
Command: npx skills add https://github.com/mostafa-ismail-2004/codex-plugin --skill api-design-mostafa-ismail-2004

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you design REST APIs that are consistent, predictable, and production-ready, reducing confusion for developers and avoiding common interface mistakes.

Core Features & Use Cases

Resource Naming and URL Structure: Defines plural, lowercase, kebab-case endpoints and sensible nested resources for clear API routing.
Status Codes, Errors, and Responses: Standardizes HTTP methods, success/error payloads, validation handling, and Location headers for created resources.
Pagination, Filtering, Sorting, and Versioning: Supports scalable list retrieval, query-based discovery, and safe API evolution over time.
Use Case: A backend team can use this Skill to review a new users endpoint, choose cursor pagination, define validation errors, and publish a versioning plan before release.

Quick Start

Ask for a REST API design review of your endpoint plan, including resource names, status codes, pagination, filtering, error responses, and versioning guidance.

Frequently Asked Questions about api-design

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

FAQPage Schema

How do I design REST API endpoints with consistent resource naming and URL structure?▼

To design REST API endpoints properly, use plural, lowercase, kebab-case resource names with sensible nested resources for clear routing. This ensures your API structure remains predictable and consistent for developers consuming it.

What HTTP status codes should I use for REST API errors and validation handling?▼

REST API error handling requires standardizing HTTP methods and using semantic status codes. You should structure consistent success and error payloads, define validation error formats, and include Location headers for created resources.

How do I implement pagination, filtering, and sorting for scalable REST API list endpoints?▼

REST API pagination supports scalable list retrieval by using cursor or offset techniques. You can combine this with query-based filtering and sorting parameters to allow clients efficient discovery of large datasets.

What is the best way to handle REST API versioning and deprecation safely?▼

REST API versioning enables safe API evolution over time by managing endpoint versions and deprecation practices. Planning version transitions ensures backward compatibility while allowing you to introduce breaking changes without disrupting consumers.

Does this REST API design approach support rate limiting and authentication planning?▼

Yes, production-grade REST API design includes defining authentication mechanisms and rate limiting strategies. These protect backend services from abuse and ensure controlled access to your API resources across common web service scenarios.

When should I review my REST API contract before a backend implementation release?▼

You should review your REST API contract when planning new endpoints, conducting API reviews, or designing public platforms. Validating resource names, pagination, and error responses before backend implementation prevents costly interface mistakes.