Agent Skills: API Design Skill

API Design Skill

Help design consistent, well-structured RESTful APIs.

Principles

URL Structure

• Use nouns for resources: /users, /orders
• Use plural forms: /users not /user
• Nest for relationships: /users/{id}/orders
• Keep URLs shallow (max 2-3 levels)

HTTP Methods

• GET: Read (idempotent, cacheable)
• POST: Create
• PUT: Full update (idempotent)
• PATCH: Partial update
• DELETE: Remove (idempotent)

Status Codes

• 200: Success
• 201: Created
• 204: No Content (successful DELETE)
• 400: Bad Request (client error)
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 409: Conflict
• 422: Unprocessable Entity (validation)
• 500: Server Error

Response Format

{
  "data": { ... },
  "meta": {
    "page": 1,
    "total": 100
  },
  "errors": [
    { "field": "email", "message": "Invalid format" }
  ]
}

Pagination

• Use cursor-based for large datasets
• Use offset-based for simple cases
• Always include: page, per_page, total, next_cursor

Versioning

• URL prefix: /v1/users
• Header: Accept: application/vnd.api+json; version=1

Checklist for New Endpoints

• [ ] Clear resource naming
• [ ] Correct HTTP method
• [ ] Appropriate status codes
• [ ] Input validation
• [ ] Error response format
• [ ] Authentication required?
• [ ] Rate limiting needed?
• [ ] Documentation updated