How do I install the REST API Design skill?

Run npx skillmds@latest add tryboy869/rest-api-design-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is REST API Design safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with REST API Design?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is REST API Design free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published REST API Design?

Tryboy869 (@tryboy869) published this skill. Their other Agent Skills are listed on their SkillMD profile.

REST API Design by tryboy869 — Agent Skill

Name: REST API Design
Author: Tryboy869

REST API Design

Apply when designing or implementing REST APIs. Covers: URL conventions, HTTP methods, status codes, versioning, pagination, error responses, OpenAPI spec. Trigger for: REST, API design, endpoints, HTTP, routes, OpenAPI, Swagger.

Tryboy869 Updated Sep 21, 2026

File contents

REST API DESIGN — Production Standards

URL Conventions

# Resources (nouns, plural, lowercase, hyphens)
GET    /jobs                    # list
POST   /jobs                    # create
GET    /jobs/{id}               # read one
PATCH  /jobs/{id}               # partial update
DELETE /jobs/{id}               # delete
POST   /jobs/{id}/retry         # action (verb after resource)
GET    /users/{id}/jobs         # nested resource

# ❌ Wrong
GET /getJob, POST /createJob, GET /job_list

HTTP Status Codes (use correctly)

200 OK              — successful GET, PATCH
201 Created         — successful POST (with Location header)
204 No Content      — successful DELETE
400 Bad Request     — validation error (return field details)
401 Unauthorized    — not authenticated
403 Forbidden       — authenticated but not allowed
404 Not Found       — resource doesn't exist
409 Conflict        — duplicate, state conflict
422 Unprocessable   — semantic validation error
429 Too Many Requests
500 Internal Error  — unexpected server error
503 Service Unavailable — dependency down

Standard Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {"field": "email", "message": "Invalid email format"},
      {"field": "age", "message": "Must be between 18 and 120"}
    ],
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Pagination (cursor-based)

GET /jobs?limit=20&cursor=eyJpZCI6MTAwfQ

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "next_cursor": "eyJpZCI6MTIwfQ",
    "has_more": true
  }
}

Versioning

/v1/jobs    # URL versioning (simplest, recommended)
# NOT: Accept: application/vnd.api+json;version=2 (complex)

OpenAPI Spec (always)

# FastAPI generates it automatically
app = FastAPI(
    title="Jobs API",
    version="1.0.0",
    description="Async job processing API",
)
# Accessible at /docs and /openapi.json

Forbidden

❌ Verbs in URLs (/getJob, /createUser) ❌ Returning 200 for errors ❌ No error details in response body ❌ Inconsistent naming (camelCase + snake_case mixed) ❌ Sensitive data in URL params (use body or headers)

---name: rest-api-design-2description: Apply when designing or implementing REST APIs. Covers: URL conventions, HTTP methods, status codes, versioning, pagination, error responses, OpenAPI spec. Trigger for: REST, API design, endpoints, HTTP, routes, OpenAPI, Swagger.---# REST API DESIGN — Production Standards## URL Conventions```# Resources (nouns, plural, lowercase, hyphens)GET /jobs # listPOST /jobs # createGET /jobs/{id} # read onePATCH /jobs/{id} # partial updateDELETE /jobs/{id} # deletePOST /jobs/{id}/retry # action (verb after resource)GET /users/{id}/jobs # nested resource# ❌ WrongGET /getJob, POST /createJob, GET /job_list```## HTTP Status Codes (use correctly)```200 OK — successful GET, PATCH201 Created — successful POST (with Location header)204 No Content — successful DELETE400 Bad Request — validation error (return field details)401 Unauthorized — not authenticated403 Forbidden — authenticated but not allowed404 Not Found — resource doesn't exist409 Conflict — duplicate, state conflict422 Unprocessable — semantic validation error429 Too Many Requests500 Internal Error — unexpected server error503 Service Unavailable — dependency down```## Standard Error Response```json{ "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [ {"field": "email", "message": "Invalid email format"}, {"field": "age", "message": "Must be between 18 and 120"} ], "request_id": "req_abc123", "timestamp": "2025-01-15T10:30:00Z" }}```## Pagination (cursor-based)```jsonGET /jobs?limit=20&cursor=eyJpZCI6MTAwfQ{ "data": [...], "pagination": { "limit": 20, "next_cursor": "eyJpZCI6MTIwfQ", "has_more": true }}```## Versioning```/v1/jobs # URL versioning (simplest, recommended)# NOT: Accept: application/vnd.api+json;version=2 (complex)```## OpenAPI Spec (always)```python# FastAPI generates it automaticallyapp = FastAPI( title="Jobs API", version="1.0.0", description="Async job processing API",)# Accessible at /docs and /openapi.json```## Forbidden❌ Verbs in URLs (/getJob, /createUser)❌ Returning 200 for errors❌ No error details in response body❌ Inconsistent naming (camelCase + snake_case mixed)❌ Sensitive data in URL params (use body or headers)

Frequently asked questions