How do I install the API Design skill?

Run npx skillmds add majiayu000/api-design-19 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: docs only. 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.5 (4 reviews)
Author: majiayu000

File contents

API Design Skill

Purpose

Create consistent, well-designed APIs.

REST Conventions

Reference: standards/rest-conventions.md

HTTP Methods

Method	Use Case	Idempotent
GET	Retrieve resource	Yes
POST	Create resource	No
PUT	Replace resource	Yes
PATCH	Partial update	No
DELETE	Remove resource	Yes

URL Patterns

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

GET    /users/:id/posts # Nested resource

Response Status Codes

Code	Meaning	Use When
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Validation error
401	Unauthorized	Auth required
403	Forbidden	Auth insufficient
404	Not Found	Resource doesn't exist
422	Unprocessable	Business rule violation
500	Server Error	Unexpected error

Error Response Format

Reference: standards/error-responses.md

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

Versioning

Reference: standards/versioning.md

Options:

URL: /api/v1/users
Header: Accept: application/vnd.api.v1+json

Recommendation: URL versioning for simplicity

Endpoint Documentation

Use template: templates/endpoint-doc.md

---name: api-design-19description: Design RESTful APIs following conventions with proper error handling, versioning, and documentation. Use when creating or modifying API endpoints.--- # API Design Skill ## Purpose Create consistent, well-designed APIs. ## REST Conventions Reference: [standards/rest-conventions.md](standards/rest-conventions.md) ### HTTP Methods | Method | Use Case | Idempotent | |--------|----------|------------| | GET | Retrieve resource | Yes | | POST | Create resource | No | | PUT | Replace resource | Yes | | PATCH | Partial update | No | | DELETE | Remove resource | Yes | ### URL Patterns ``` GET /users # List users GET /users/:id # Get user POST /users # Create user PUT /users/:id # Replace user PATCH /users/:id # Update user DELETE /users/:id # Delete user GET /users/:id/posts # Nested resource ``` ### Response Status Codes | Code | Meaning | Use When | |------|---------|----------| | 200 | OK | Successful GET, PUT, PATCH | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Validation error | | 401 | Unauthorized | Auth required | | 403 | Forbidden | Auth insufficient | | 404 | Not Found | Resource doesn't exist | | 422 | Unprocessable | Business rule violation | | 500 | Server Error | Unexpected error | ## Error Response Format Reference: [standards/error-responses.md](standards/error-responses.md) ```json { "error": { "code": "VALIDATION_ERROR", "message": "Validation failed", "details": [ { "field": "email", "message": "Invalid email format" } ] } } ``` ## Versioning Reference: [standards/versioning.md](standards/versioning.md) Options: - URL: `/api/v1/users` - Header: `Accept: application/vnd.api.v1+json` Recommendation: URL versioning for simplicity ## Endpoint Documentation Use template: [templates/endpoint-doc.md](templates/endpoint-doc.md)

Frequently asked questions