Menu
API development expert including REST design, OpenAPI, and documentation
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/oimiragieo/agent-studio --skill api-development-expertThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Based on SOC occupation classification
| name | api-development-expert |
| description | API development expert including REST design, OpenAPI, and documentation |
| version | 1.2.0 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Edit","Bash","Grep","Glob"] |
| consolidated_from | 1 skills |
| best_practices | ["Follow domain-specific conventions","Apply patterns consistently","Prioritize type safety and testing","Use OpenAPI 3.1 for full JSON Schema 2020-12 compliance and webhook support","Apply versioning strategy consistently from day one","Use HATEOAS links for discoverable APIs (Richardson Maturity Level 3)"] |
| error_handling | graceful |
| streaming | supported |
| verified | true |
| lastVerifiedAt | "2026-02-19T06:00:00.000Z" |
| source | builtin |
| trust_score | 100 |
| provenance_sha | 3d79643b9b9dcb24 |
When designing REST APIs, follow these core architectural principles:
Resource-Oriented Design
/users, /products, /orders/getUsers, /createProduct/users/{userId}/orders (orders belonging to a user)/product-details not /productdetails/users not /users/HTTP Methods (Verbs with Purpose)
GET - Retrieve resources (idempotent & safe, no side effects)POST - Create new resources (not idempotent, returns 201 Created with Location header)PUT - Replace entire resource or upsert (idempotent)PATCH - Partial update (not idempotent, use application/json-patch+json)DELETE - Remove resource (idempotent, returns 204 No Content or 200 OK)Query Parameters for Filtering, Sorting, and Pagination
/products?category=electronics&price_gt=100/products?sort_by=price&order=desc/products?page=2&limit=10
Choose one and stick to it:
/v1/users, /api/v2/products
Accept: application/vnd.myapi.v1+jsonUse OpenAPI 3.0+ to define your API specification:
Benefits:
Define schemas for:
Example: Define validation rules so invalid requests are caught before reaching your backend
Protect against abuse and ensure fair usage:
Implementation strategies:
429 Too Many Requests status codeX-RateLimit-Limit: 1000X-RateLimit-Remaining: 999X-RateLimit-Reset: 1640000000Consistent Error Response Structure:
{
"error": {
"code": "validation_error",
"message": "Input validation failed.",
"details": [{ "field": "email", "message": "Invalid email format." }]
}
}
Use Appropriate HTTP Status Codes:
2xx Success: 200 OK, 201 Created, 204 No Content
3xx Redirection: 301 Moved Permanently, 304 Not Modified
4xx Client Error:
400 Bad Request - General client error401 Unauthorized - Authentication missing/failed403 Forbidden - Authenticated but no permission404 Not Found - Resource doesn't exist405 Method Not Allowed - Invalid HTTP method409 Conflict - Resource already exists422 Unprocessable Entity - Semantic validation error429 Too Many Requests - Rate limiting5xx Server Error:
500 Internal Server Error - Generic server error503 Service Unavailable - Service temporarily downProvide machine-readable codes AND human-readable messages
OAuth 2.1 (Industry standard for delegated authorization)
JWT (JSON Web Tokens) for stateless authentication:
API Keys for simpler integrations:
HTTP Caching Headers:
Cache-Control: max-age=3600 - Cache for 1 hourETag - Entity tag for conditional requestsExpires - Absolute expiration time304 Not Modified - Return for unchanged resourcesCaching strategies:
Optimization techniques:
?fields=id,name)202 Accepted with status endpointComprehensive documentation must include:
Use tools:
Upgrade from OpenAPI 3.0 to 3.1 for full JSON Schema 2020-12 compliance:
Key differences from 3.0:
| Feature | OpenAPI 3.0 | OpenAPI 3.1 |
|---|---|---|
| JSON Schema compliance | Subset + extensions | Full JSON Schema 2020-12 |
| Nullable fields | nullable: true | type: ["string", "null"] |
| Webhooks | Not supported | webhooks object at root |
$schema declaration | Not allowed | Allowed at document root |
example vs examples | Both allowed together | Mutually exclusive |
OpenAPI 3.1 Webhook definition:
openapi: '3.1.0'
info:
title: My API
version: '1.0.0'
webhooks:
orderCreated:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEvent'
responses:
'200':
description: Webhook received successfully
OpenAPI Overlays (v1.1.0, Jan 2026):
Overlays are a companion spec that applies targeted transformations to an OpenAPI document without modifying the source. Use cases:
# overlay.yaml
overlay: '1.0.0'
info:
title: Partner API Overlay
version: '1.0.0'
actions:
- target: "$.paths['/internal/**']"
remove: true
- target: '$.info'
update:
x-partner-id: 'acme-corp'
OpenAPI 3.2 (September 2025) adds:
summary, parent, kind)itemSchemaquery HTTP operations and querystring parametersChoose and document your versioning strategy before the first public release:
URI versioning (most common, most explicit):
GET /v1/users
GET /v2/users
Header versioning:
Accept: application/vnd.myapi.v2+json
Deprecation lifecycle:
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"
GraphQL schema evolution (no URI versioning needed):
@deprecated(reason: "Use newField instead") to phase out fieldsStandardized headers (IETF draft draft-ietf-httpapi-ratelimit-headers):
RateLimit-Limit: 100
RateLimit-Remaining: 87
RateLimit-Reset: 1
Retry-After: 30
Algorithm comparison:
| Algorithm | Burst Handling | Accuracy | Use Case |
|---|---|---|---|
| Fixed window | Allows boundary bursts | Low | Simple rate caps |
| Sliding window log | No burst | High | Strict SLAs |
| Sliding window counter | Small burst | Medium | General purpose |
| Token bucket | Controlled burst | High | API gateways |
| Leaky bucket | No burst (smoothed) | High | Traffic shaping |
Tiered rate limiting — differentiate by caller type:
rate_limits:
anonymous: 60/hour
authenticated: 1000/hour
premium: 10000/hour
internal_service: unlimited
Design APIs for discoverability — include hypermedia links so clients can navigate state transitions:
Richardson Maturity Levels:
| Level | Description | Example |
|---|---|---|
| 0 | Single endpoint (RPC over HTTP) | POST /api with action field |
| 1 | Resource-based URIs | GET /users/123 |
| 2 | HTTP verbs + status codes | DELETE /users/123 returns 204 |
| 3 | HATEOAS (hypermedia controls) | Response includes _links |
Level 3 example response:
{
"id": "order-42",
"status": "pending",
"total": 99.99,
"_links": {
"self": { "href": "/orders/42" },
"confirm": { "href": "/orders/42/confirm", "method": "POST" },
"cancel": { "href": "/orders/42/cancel", "method": "DELETE" },
"customer": { "href": "/users/7" }
}
}
Level 3 is aspirational; most production APIs operate at Level 2 and selectively add hypermedia links for complex workflows.
For microservices architectures using GraphQL, federation enables a unified supergraph from distributed subgraphs:
Core concepts:
Best practices:
User) can be defined in its owning subgraph and extended in others using @key and @extends/v1/, /v2/) so clients can migrate on their schedule.Retry-After header.| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
Verbs in URIs (/getUser, /createOrder) | Violates REST constraints; HTTP method conveys the verb | Use nouns: /users, /orders with GET/POST |
| No API versioning from day 1 | Breaking changes instantly break all existing clients | URI versioning: /v1/resource from the start |
| Returning 200 OK for errors | Clients can't distinguish success from failure programmatically | Use correct HTTP status codes |
| No rate limiting on public endpoints | DoS vulnerability; single client can exhaust resources | Rate limit with X-RateLimit-* headers + 429 |
| Leaking server internals in errors | Stack traces and DB errors are attack vectors | Return error codes + safe messages only |
| No OpenAPI specification | Clients must guess request/response format | Document all endpoints in OpenAPI 3.1 |
This expert skill consolidates 1 individual skills:
Before starting:
cat .claude/context/memory/learnings.md
After completing: Record any new patterns or exceptions discovered.
ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.
Agent frontmatter enhancements — disallowedTools, mcpServers scoping, fork_eligible field
Context management — pre-compact persistence, threshold alignment, microcompact/circuit breaker detection
Hook enhancements — updatedInput for bash safety prefixes, suppressOutput for verbose blocks, denial-based routing feedback