api-design

Design REST APIs with versioning, pagination, filtering, and OpenAPI docs.

3|Updated Mar 5, 2026

Search Tags:#design #versioning #security #api #openapi #rest #pagination

Ready to run

npx skills add https://github.com/bipinks/ghost-office --skill api-design-bipinks

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/bipinks/ghost-office/tree/main/.claude/skills/api-design
Command: npx skills add https://github.com/bipinks/ghost-office --skill api-design-bipinks

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing and implementing consistent REST APIs to prevent integration issues and governance drift across services.

Core Features & Use Cases

RESTful resource design, versioning, pagination, filtering, and robust error handling.
OpenAPI documentation and HATEOAS support to improve client discoverability and integration.
Use Case: Standardized APIs across a microservices portfolio enable faster onboarding and fewer breaking changes.

Quick Start

Define a REST API design for a new service with versioned endpoints, consistent pagination and filtering, and an OpenAPI specification.

Frequently Asked Questions about api-design

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

FAQPage Schema

How do I design a REST API with versioning and pagination?▼

REST API design with versioning and pagination applies consistent conventions like versioned routes to enable scalable backend services. This approach standardizes APIs across microservices, preventing integration issues and governance drift.

What is HATEOAS and how does it improve API discoverability?▼

HATEOAS improves REST API discoverability by including hyperlinks in responses, allowing clients to dynamically navigate services. Combined with OpenAPI documentation, it enhances client integration and standardizes interactions across microservices.

What is the best way to handle errors in a REST API?▼

The best way to handle REST API errors is implementing structured error envelopes. This robust error handling mechanism ensures consistent error reporting across services, preventing integration issues and improving client integration.

Can I use this approach for both monoliths and microservices?▼

Yes, this REST API design approach applies to backend services of varying sizes, including both monoliths and microservices. It ensures consistent conventions for versioning, filtering, and rate limiting across different service architectures.

How do I generate OpenAPI documentation for a new service?▼

Generate OpenAPI documentation for a new service by defining a REST API design with versioned endpoints, consistent pagination, and filtering. This improves client discoverability and integration while ensuring secure API documentation across frameworks.

Why do I need rate limiting in my REST API?▼

Rate limiting is needed in REST API design to control traffic and protect backend services from overload. It is a core feature of robust API governance, ensuring scalable and consistent service availability across microservices.