api-design

Design REST API contracts with standardized naming, HTTP methods, and response formats.

Updated May 11, 2026
One-click install
npx skills add https://github.com/CZ-X-Ya/oh-my-csharp-skills --skill api-design-cz-x-ya
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/CZ-X-Ya/oh-my-csharp-skills/tree/main/api-design
Command: npx skills add https://github.com/CZ-X-Ya/oh-my-csharp-skills --skill api-design-cz-x-ya

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you avoid inconsistent, fragile REST API contracts by standardizing resource naming, HTTP semantics, status codes, error payloads, and pagination/filtering behaviors.

Core Features & Use Cases

  • Resource and URL design: Produce predictable, developer-friendly endpoint structures using plural nouns and kebab-case, including nested sub-resources and restrained action endpoints.
  • HTTP correctness: Map operations to safe/idempotent methods and choose appropriate success and client/server error codes, including structured validation and conflict responses.
  • Scalable list patterns: Implement offset or cursor pagination, plus filtering, sorting, search-like query parameters, sparse fieldsets, and consistent response shapes.
  • Production API concerns: Plan versioning strategy, apply authentication/authorization concepts, and define rate limiting headers and tiers.

Quick Start

Use the api-design skill to generate REST API endpoint conventions, request/response schemas, and error handling guidance for a new or reviewed service.

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 endpoint naming and URL structures?

REST API endpoint design uses predictable, developer-friendly structures with plural nouns and kebab-case. It covers nested sub-resources and restrained action endpoints to ensure consistent URL behavior across your service contracts.

What HTTP status codes and error response formats should my REST API use?

REST API error responses require standardized status codes and structured payloads for validation and conflict scenarios. HTTP correctness maps operations to safe, idempotent methods and selects appropriate success, client, and server error codes.

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

Scalable REST API list endpoints implement offset or cursor pagination alongside filtering, sorting, and sparse fieldsets. This ensures consistent response shapes for large datasets returned from your service.

Does this REST API design guidance work with ASP.NET Core, Python, and Go?

The REST API design guidance provides implementation-ready examples specifically for C# ASP.NET Core, Python, and Go. It applies to designing or reviewing API contracts across these language ecosystems.

What is the best way to plan API versioning and rate limiting for public APIs?

Production REST APIs plan versioning strategy and define rate limiting headers and tiers to manage access. This approach standardizes public or partner API consumption while maintaining backward compatibility.

Why do my REST API contracts become inconsistent and fragile over time?

REST API contracts become fragile without standardizing resource naming, HTTP semantics, status codes, and error payloads. Applying consistent design conventions prevents brittle endpoint behavior and simplifies developer integration.