api-design

Define REST API patterns for naming, status codes, pagination, and versioning.

1|Updated Mar 23, 2026
One-click install
npx skills add https://github.com/sbalagan22/bloomr --skill api-design-sbalagan22
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/sbalagan22/bloomr/tree/main/.claude/skills/api-design
Command: npx skills add https://github.com/sbalagan22/bloomr --skill api-design-sbalagan22

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST API design often suffers from inconsistent naming, poor error handling, and confusing versioning, making contracts hard to maintain and hard to onboard new developers.

Core Features & Use Cases

  • Resource naming conventions: kebab-case plural endpoints and consistent nested resources.
  • HTTP semantics & status codes: correct use of GET/POST/PUT/PATCH/DELETE with meaningful status responses.
  • Pagination, filtering, and sorting: scalable patterns for offset and cursor-based approaches.
  • Error responses & validation: standard error envelope with codes and details; versioning strategy.
  • Use Case: design a public API for a SaaS product with clear contracts and predictable errors.

Quick Start

Provide a clean, production-ready API design blueprint for a new service that follows the conventions above.

Frequently Asked Questions about api-design

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

FAQPage Schema
What are the best patterns for REST API resource naming and error handling?

REST API design patterns standardize resource naming using kebab-case plural endpoints and define standard error envelopes with consistent codes. This ensures predictable contracts, making production services easier to maintain and onboard new developers.

How do I design pagination and filtering for a scalable REST API?

Design REST API pagination and filtering by applying scalable patterns like offset and cursor-based approaches. This provides a consistent syntax for sorting and retrieving large datasets without overwhelming production services.

Which HTTP status codes and methods should I use for REST API endpoints?

Use correct HTTP semantics by mapping GET, POST, PUT, PATCH, and DELETE methods to meaningful status code responses. This ensures clear communication of API operation results and predictable behavior across resource endpoints.

How do I implement versioning and rate limiting in a public SaaS REST API?

Implement REST API versioning and rate limiting by following explicit versioning guidance and rate limiting specifications. This delivers clear contracts and predictable errors for public SaaS product endpoints.

Can I use these REST API design rules to audit existing API contracts?

Yes, you can apply these REST API design rules to audit existing API contracts. The concrete naming rules, status codes, and error response formats drive consistent behavior and design reviews across production services.