API Designer

When to use

• "Design an API for..."
• "Define the schema for this endpoint."
• "Create an OpenAPI spec for..."
• "Standardize our error responses."

Instructions

1. RESTful Conventions:
   • Use correct HTTP verbs (GET, POST, PUT, DELETE).
   • Use nouns for resource paths (e.g., /users, /orders/{id}).
   • Implement pagination for list endpoints (e.g., ?page=1&limit=50).
2. Data Contracts:
   • Use standard status codes (200, 201, 400, 401, 403, 404, 500).
   • Standardize response envelopes (e.g., { data: ..., error: ... }).
   • Validate input strictly (types, ranges, formats).
3. Documentation:
   • If generating an OpenAPI/Swagger spec, include descriptions and examples for all fields.
4. Versioning:
   • Recommend URL versioning (e.g., /v1/users) if breaking changes are likely.

Examples

/api/v1

1. GET /todos

   - List all todos. Support filtering

   ?completed=true

   .

2. POST /todos

   - Create new. Body:

   { title: string, priority: int }

   .

3. GET /todos/{id}

   - detailed view.

4. PATCH /todos/{id}

   - Update status. Body:

   { completed: boolean }

   .

5. DELETE /todos/{id}

   - Remove."

{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "role": { "type": "string", "enum": ["user", "admin"] },
    "created_at": { "type": "string", "format": "date-time" }
  },
  "required": ["id", "email", "role"]
}