Design and review intuitive, scalable, maintainable HTTP APIs. Use this skill whenever the user wants to design a new REST API, review an existing API or spec, write OpenAPI 3.x definitions, or work with HTTP semantics (GET/POST/PUT/PATCH/DELETE), status codes, idempotency (Idempotency-Key), error envelopes (RFC 7807 problem+json), pagination, filtering, versioning, or API auth (API keys, OAuth2 client credentials, rate limits). Also trigger for "API design", "RESTful", "endpoints", "OpenAPI…
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# API Design
HTTP APIs are the contract between your service and every client that consumes it. A well-designed API is consistent and predictable: the URL says which resource you are touching, the HTTP method says what happens to it, and the status code plus body say whether it worked and why not. This skill covers designing and reviewing such APIs — resource modeling, HTTP semantics, status codes, error envelopes, pagination, versioning, spec-first OpenAPI 3.x, and authentication basics — REST first, with GraphQL and gRPC covered in passing.
## Quick Reference
| Task | Reference |
|------|-----------|
| Error envelopes, RFC 7807, idempotency keys, retry policy | [error-handling.md](references/error-handling.md) |
| Cursor vs offset pagination, filtering, sorting, field selection | [pagination-filtering.md](references/pagination-filtering.md) |
| Versioning strategies, backward compatibility, deprecation | [versioning-evolution.md](references/versioning-evolution.md) |
## Core Workflow
Design an endpoint set in five steps:
…
The line at the top of this page pins the label git:20260813.4b33420, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
GET https://markdownregistry.com/api/v1/artifacts/art_r5zj63b4kdpcvys5
GET https://markdownregistry.com/api/v1/resolve?ref=svngoku/coding-agents-skills/api-design
GET https://markdownregistry.com/api/v1/blob/59290f522958425a6b2666606002dba7a4a733a2f547e3126d351b9b16690670
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
svngoku/coding-agents-skills · skills/adaption-ai/SKILL.md · Adaption AI SDK for synthetic data augmentation and dataset adaptation. Use when building data pipelines with the…
svngoku/coding-agents-skills · skills/database-design/SKILL.md · Design relational database schemas (and choose when to go NoSQL) that stay maintainable and fast. Use this skill…
svngoku/coding-agents-skills · skills/ddd/SKILL.md · Domain-Driven Design system for software development. Use when designing new systems with DDD principles, refactoring…
svngoku/coding-agents-skills · skills/genai-tk/SKILL.md · Build GenAI and agentic apps with genai-tk (tclatos/genai-tk), a YAML-driven IoC toolkit over LangChain, DeepAgents…
svngoku/coding-agents-skills · skills/langchain/SKILL.md · Build AI agents with LangChain v1 and LangGraph in Python. Use this skill whenever the user mentions LangChain…
svngoku/coding-agents-skills · skills/microservices-patterns/SKILL.md · Decompose systems into microservices and apply canonical distributed-systems patterns. Use this skill whenever the user…
svngoku/coding-agents-skills · skills/performance-optimization/SKILL.md · Systematically find and fix performance problems in applications, frontend and backend, by measuring first. Use this…
svngoku/coding-agents-skills · skills/prime-rl/SKILL.md · Post-train LLMs with PrimeIntellect's prime-rl (async RL, SFT, distillation, evals). Use this skill whenever the user…
svngoku/coding-agents-skills · skills/scalingo/SKILL.md · Scalingo is a European (French) Platform-as-a-Service for deploying and operating web applications, background workers…
svngoku/coding-agents-skills · skills/security-best-practices/SKILL.md · Practical security review and hardening guidance for application code in Python, JavaScript/TypeScript, and Go. Use…
svngoku/coding-agents-skills · skills/smolagents/SKILL.md · Build AI agents with Hugging Face's SmolAgents framework. Use when creating code-executing agents, tool-calling agents…
affaan-m/ecc · docs/es/skills/api-design/SKILL.md · Patrones de diseño REST API incluyendo nomenclatura de recursos, códigos de estado, paginación, filtrado, respuestas de…
yonatangross/orchestkit · plugins/ork/skills/api-design/SKILL.md · API contract design for REST and GraphQL, covering resource shape, URL and header versioning with deprecation windows…
yonatangross/orchestkit · src/skills/api-design/SKILL.md · API contract design for REST and GraphQL, covering resource shape, URL and header versioning with deprecation windows…
