skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
vekzz-dev/opencode-skills52 installs

api-design

REST API design best practices: resource naming, versioning, error handling, pagination, HATEOAS, rate limiting, OpenAPI documentation. Trigger: API design, REST API, endpoint, OpenAPI, RESTful, API versioning, or API documentation.

How do I install this agent skill?

npx skills add https://github.com/vekzz-dev/opencode-skills --skill api-design
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill is a comprehensive reference guide for REST API design best practices. It provides architectural patterns and examples for resource naming, error handling, versioning, and documentation without any malicious code or security risks.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

When to Use

  • Designing a new REST API
  • Reviewing or refactoring existing endpoints
  • Defining error responses, pagination, or versioning strategy
  • Writing OpenAPI/Swagger documentation
  • Implementing HATEOAS or rate limiting

Instructions

1. Resource Naming

PatternExampleNotes
GET /resourcesGET /usersList collection
POST /resourcesPOST /usersCreate (return 201 + Location header)
GET /resources/:idGET /users/42Single resource
PUT /resources/:idPUT /users/42Full replace
PATCH /resources/:idPATCH /users/42Partial update
DELETE /resources/:idDELETE /users/42Delete
GET /resources/:id/subresourcesGET /users/42/ordersSub-collection
POST /resources/:id/subresourcesPOST /users/42/ordersCreate sub-resource

Rules:

  • Plural nouns, not verbs: /users not /getUsers
  • Consistent casing: kebab-case or snake_case, not mixed
  • Nest by ownership, not by convenience: max 2 levels deep
  • Verbs only for actions that are not CRUD: POST /orders/42/cancel

2. Versioning

StrategyHowProsCons
URI pathGET /v1/usersExplicit, cacheable, easy to routeURL pollution on breaking changes
HeaderAccept: application/vnd.myapp.v1+jsonClean URLs, content negotiationHarder to discover, caching complexity
Query paramGET /users?version=1Easy to testPollutes query space, not cache-friendly

Recommendation: URI path for public APIs, header for internal/microservices.

3. Error Handling (RFC 9457 / application/problem+json)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/order/invalid-status",
  "title": "Invalid order status transition",
  "status": 422,
  "detail": "Cannot transition order 42 from 'shipped' to 'pending'.",
  "instance": "/orders/42",
  "timestamp": "2025-05-31T10:30:00Z"
}

Always use consistent error envelope. Map HTTP status codes semantically:

CodeWhen
400Malformed request body / validation error
401Missing or invalid authentication
403Authenticated but not authorized
404Resource not found
409Conflict (duplicate, stale version)
422Unprocessable entity (business rule violation)
429Rate limited
500Unexpected server error (never leak details)

Never return 5xx for client errors or 4xx for server faults.

4. Pagination

Cursor-based (preferred for large datasets):

GET /users?cursor=eyJpZCI6NDJ9&limit=20

{
  "data": [...],
  "pagination": {
    "next": "eyJpZCI6NjJ9",
    "limit": 20
  }
}

Offset-based (acceptable for small/admin datasets):

GET /users?page=1&size=20

{
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 150,
    "total_pages": 8
  }
}

5. HATEOAS

Guide clients via links in responses — they don't hardcode URLs:

GET /orders/42

{
  "id": 42,
  "status": "pending",
  "_links": {
    "self": { "href": "/orders/42" },
    "cancel": { "href": "/orders/42/cancel", "method": "POST" },
    "pay": { "href": "/orders/42/pay", "method": "POST" }
  }
}

Spring Boot: org.springframework.boot:spring-boot-starter-hateoas

6. Rate Limiting

StrategyHowBest for
Token bucketFixed rate, burst allowedGeneral purpose
Sliding windowRolling time windowStrict rate enforcement
Leaky bucketSmooth output rateQueue processing

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1717142400

OpenAPI / SpringDoc

Use springdoc-openapi (springdoc-openapi-starter-webmvc-ui for Boot 3+):

@Operation(summary = "List all users", description = "Returns paginated list of active users")
@ApiResponse(responseCode = "200", description = "Users found")
@ApiResponse(responseCode = "401", description = "Unauthorized")
@GetMapping
public ResponseEntity<Page<UserResponse>> listUsers(
    @Parameter(description = "Cursor for pagination") @RequestParam(required = false) String cursor
) { ... }

Annotate every endpoint — don't rely on auto-generated names.

Anti-Patterns

  • /api prefix on every route — api.example.com or gateway takes care of it
  • Nested resources beyond 3 levels — /a/1/b/2/c/3/d/4 is unreadable; use query params
  • Returning 200 with error in body — use correct HTTP status codes
  • Leaking stack traces in production responses — use @ControllerAdvice to sanitize
  • Breaking existing clients without versioning or migration window
  • /getAllUsers — REST uses HTTP methods, not verbs in the URL

Commands

# Generate OpenAPI spec at runtime
curl localhost:8080/v3/api-docs | jq .

# OpenAPI UI
open http://localhost:8080/swagger-ui.html

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/vekzz-dev/opencode-skills/api-design">View api-design on skillZs</a>