api-design is agent-read markdown (skill) from jnpiyush/agentx: Design robust REST APIs with proper versioning, pagination, error handling, rate limiting, and documentation. Use when creating new API endpoints, designing resource naming conventions, implementing pagination or filtering, adding rate limiting, or documenting APIs with OpenAPI/Swagger..
Indexed from public GitHub and served as immutable, content-addressed versions. Install it pinned to an exact SHA-256 with the mdr CLI, and every file is verified against the hash recorded here before it reaches your agent. The deterministic audit below grades the latest version, and the same file always earns the same grade.
What the file says
# API Design
> **Purpose**: Design robust, maintainable, and user-friendly REST APIs.
> **Focus**: Resource naming, HTTP methods, status codes, versioning, documentation.
> **Note**: Language-agnostic patterns applicable to any tech stack.
---
## When to Use This Skill
- Designing new REST API endpoints
- Implementing pagination, filtering, or sorting
- Adding rate limiting or CORS configuration
- Documenting APIs with OpenAPI/Swagger
- Designing webhook notification systems
## Prerequisites
- HTTP protocol fundamentals
- JSON data format understanding
## Decision Tree
```
Designing an API endpoint?
+- What operation?
| +- Read data -> GET (idempotent, cacheable)
| +- Create resource -> POST (returns 201 + Location header)
| +- Full update -> PUT (idempotent, replaces entire resource)
| +- Partial update -> PATCH (only changed fields)
| - Remove -> DELETE (idempotent, returns 204)
+- Returns collection?
| - Add pagination (cursor or offset) + filtering + sorting
+- Versioning needed?
| +- URL path versioning -> /api/v1/resources (recommended)
| - Header versioning -> Accept: application/vnd.api.v1+json
+- Error handling?
…
Pin to a label to follow the author's releases, or to a sha256 to freeze the exact bytes forever. Either way the resolved hash is written to mdr.lock, and mdr install reproduces it on any machine.
GET https://markdownregistry.com/api/v1/artifacts/art_vbwqec4s7yvnzsf4
GET https://markdownregistry.com/api/v1/resolve?ref=jnpiyush/agentx/api-design
GET https://markdownregistry.com/api/v1/blob/908627d57eda3946b7311a7c7102858a6533229d5e4b9a6cee6008c7f4b15290
Your agent 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.
jnpiyush/agentx · .github/skills/ai-systems/agent-observability/SKILL.md · Instrument LLM agents with tracing, metrics, and evaluation telemetry. Use when adding OpenTelemetry GenAI semantic…
jnpiyush/agentx · .github/skills/ai-systems/ai-agent-development/SKILL.md · Build production-ready AI agents with Microsoft Foundry and Agent Framework. Use when creating AI agents, selecting LLM…
jnpiyush/agentx · .github/skills/ai-systems/ai-evaluation/SKILL.md · Use when evaluating AI quality, safety, completeness and cost with held-out tasks, executable graders, calibrated…
jnpiyush/agentx · .github/skills/ai-systems/ai-safety-and-red-teaming/SKILL.md · Defend LLM systems against prompt injection, jailbreaks, data exfiltration, and unsafe output. Covers input/output…
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…
majiayu000/spellbook · skills/api-design/SKILL.md · REST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers…
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…
