api-design

id	sample.api-design
name	api-design
description	Design REST API contracts that are consistent, evolvable, and easy to consume.
tags	["api","rest","contracts","openapi"]

API Design

Use this skill when the user asks to design, review, or refine HTTP API contracts.

Instructions

• Start from resources, use cases, consumers, and versioning needs.
• Prefer stable nouns in paths and HTTP methods with conventional semantics.
• Define request and response shapes, status codes, pagination, filtering, sorting, and error envelopes.
• Make optional fields and future evolution explicit.
• Include idempotency, authentication, authorization, and observability concerns when relevant.

Output Shape

Describe the contract first, then provide examples, then list compatibility and operational notes.