Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →jamestorrevillas/api-design
Use this skill when designing or reviewing APIs — REST, GraphQL, tRPC, or gRPC. Trigger on keywords: API design, REST, GraphQL, tRPC, gRPC, endpoint, schema, route, OpenAPI, Swagger, API versioning, pagination, API contract, HTTP methods.
Passed 23 of 23 test cases with the skill, and 20 of 23 without it.
and 1 more in the full report
3 fixed20 passed either way0 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 3 test cases the skill fixed. Same model, same prompt, with and without the skill.
Our engineering team wants to standardize our REST response formats and HTTP status codes across all microservices. Please provide a guide illustrating standard JSON payload envelopes for collection lists with metadata, single resource objects, and detailed validation error payloads, as well as the appropriate status codes to return for resource creation, partial updates, and authorization failures.
| Checked | Without skill | With skill |
|---|---|---|
| Collection pagination metadata includes perPage key | Missed | Passed |
| Collection metadata includes total key | Missed | Passed |
| Single resource response wraps the object in a top-level data property | Passed | Passed |
| Error response envelope wraps payload in a top-level error object containing code, message, and details | Passed | Passed |
| Resource creation returns HTTP status code 201 | Passed | Passed |
| Partial update returns HTTP status code 200 | Passed | Passed |
| Authorization failure for authenticated user returns HTTP status code 403 | Passed | Passed |
The instructions your model reads when the skill loads.
| Type | Best For | Avoid When |
|---|---|---|
| REST | Public APIs, CRUD, simple clients, IoT | Complex nested data, rapid schema iteration |
| GraphQL | Mobile apps, complex nested data, multiple clients | Simple CRUD, small teams new to it |
| tRPC | TypeScript monorepos, internal full-stack TS APIs | Non-TypeScript clients, public APIs |
| gRPC | High-performance microservice comms, streaming | Browser clients, simple use cases |
GET /users ← list
GET /users/{id} ← single
POST /users ← create
PUT /users/{id} ← replace
PATCH /users/{id} ← partial update
DELETE /users/{id} ← delete
# Nested resources
GET /users/{id}/orders
POST /users/{id}/orders
# Actions (when REST verbs aren't enough)
POST /orders/{id}/cancel
POST /users/{id}/activate
| Code | Use When |
|---|---|
| 200 | Successful GET, PUT, PATCH |
| 201 | Successful POST that creates |
| 204 | Successful DELETE (no body) |
| 400 | Validation failure, bad request |
test cases passed, vs 20 / 23 without
Published skills whose descriptions closely match this one, with their headline benchmark lift.
More skills from the same source and nearby in the registry, with their headline benchmark lift.