How do I install the API Design skill?

Run npx skillmds add majiayu000/api-design 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 API Design safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with 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 API Design free to use?

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

Who published API Design?

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

API Design by majiayu000 — Agent Skill

Name: API Design
Rating: 4.2 (5 reviews)
Author: majiayu000

File contents

API Design Principles

REST Conventions

HTTP Methods

Method	Purpose	Idempotent
GET	Retrieve resource(s)	Yes
POST	Create new resource	No
PUT	Replace entire resource	Yes
PATCH	Partial update	Yes
DELETE	Remove resource	Yes

URL Structure

GET    /api/v1/users           # List all users
GET    /api/v1/users/:id       # Get single user
POST   /api/v1/users           # Create user
PUT    /api/v1/users/:id       # Replace user
PATCH  /api/v1/users/:id       # Update user
DELETE /api/v1/users/:id       # Delete user

# Nested resources
GET    /api/v1/users/:id/posts # User's posts

Response Format

Success Response

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

HTTP Status Codes

Success (2xx)

200 OK - Successful GET, PUT, PATCH
201 Created - Successful POST
204 No Content - Successful DELETE

Client Errors (4xx)

400 Bad Request - Invalid input
401 Unauthorized - Authentication required
403 Forbidden - Permission denied
404 Not Found - Resource doesn't exist
409 Conflict - Resource conflict
422 Unprocessable Entity - Validation failed

Server Errors (5xx)

500 Internal Server Error - Unexpected error
503 Service Unavailable - Temporary unavailable

Pagination

Offset-based

GET /api/v1/users?page=2&limit=20

Cursor-based

GET /api/v1/users?cursor=abc123&limit=20

Filtering & Sorting

GET /api/v1/users?status=active&role=admin
GET /api/v1/users?sort=-created_at,name
GET /api/v1/users?fields=id,name,email

Authentication

JWT Token

Authorization: Bearer <token>

API Key

X-API-Key: <api-key>

Versioning

URL Path (Recommended)

/api/v1/users
/api/v2/users

Header

Accept: application/vnd.api+json; version=1

Rate Limiting Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

---name: api-designdescription: RESTful API design principles, patterns, and best practices. Use when building backend APIs. (project)--- # API Design Principles ## REST Conventions ### HTTP Methods | Method | Purpose | Idempotent | |--------|---------|------------| | GET | Retrieve resource(s) | Yes | | POST | Create new resource | No | | PUT | Replace entire resource | Yes | | PATCH | Partial update | Yes | | DELETE | Remove resource | Yes | ### URL Structure ``` GET /api/v1/users # List all users GET /api/v1/users/:id # Get single user POST /api/v1/users # Create user PUT /api/v1/users/:id # Replace user PATCH /api/v1/users/:id # Update user DELETE /api/v1/users/:id # Delete user # Nested resources GET /api/v1/users/:id/posts # User's posts ``` ## Response Format ### Success Response ```json { "data": { ... }, "meta": { "page": 1, "limit": 20, "total": 100 } } ``` ### Error Response ```json { "error": { "code": "VALIDATION_ERROR", "message": "Invalid input data", "details": [ { "field": "email", "message": "Invalid email format" } ] } } ``` ## HTTP Status Codes ### Success (2xx) - `200 OK` - Successful GET, PUT, PATCH - `201 Created` - Successful POST - `204 No Content` - Successful DELETE ### Client Errors (4xx) - `400 Bad Request` - Invalid input - `401 Unauthorized` - Authentication required - `403 Forbidden` - Permission denied - `404 Not Found` - Resource doesn't exist - `409 Conflict` - Resource conflict - `422 Unprocessable Entity` - Validation failed ### Server Errors (5xx) - `500 Internal Server Error` - Unexpected error - `503 Service Unavailable` - Temporary unavailable ## Pagination ### Offset-based ``` GET /api/v1/users?page=2&limit=20 ``` ### Cursor-based ``` GET /api/v1/users?cursor=abc123&limit=20 ``` ## Filtering & Sorting ``` GET /api/v1/users?status=active&role=admin GET /api/v1/users?sort=-created_at,name GET /api/v1/users?fields=id,name,email ``` ## Authentication ### JWT Token ``` Authorization: Bearer <token> ``` ### API Key ``` X-API-Key: <api-key> ``` ## Versioning ### URL Path (Recommended) ``` /api/v1/users /api/v2/users ``` ### Header ``` Accept: application/vnd.api+json; version=1 ``` ## Rate Limiting Headers ``` X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640000000 ```

Frequently asked questions