Agent skill

api-design

Design RESTful APIs following conventions with proper error handling, versioning, and documentation. Use when creating or modifying API endpoints.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/api-design-junior-frontend-dev-hi-u-ng

SKILL.md

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

json
{
  "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

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results