AI for REST API Design — Generate OpenAPI Specs and Consistent Endpoints

Design a RESTful API for a project management tool with these resources:
- Projects (owned by a team)
- Tasks (belong to a project, assigned to a user)
- Comments (belong to a task)
 
Include: resource URLs, HTTP methods, request/response body shapes,
status codes for success and common errors, and pagination for list endpoints.
Use snake_case for JSON keys.

GET    /projects                    List all projects for the authenticated team
POST   /projects                    Create a new project
GET    /projects/:id                Get a single project
PATCH  /projects/:id                Update project fields
DELETE /projects/:id                Delete a project (and all its tasks)
 
GET    /projects/:id/tasks          List tasks in a project (paginated)
POST   /projects/:id/tasks          Create a task in a project
GET    /projects/:id/tasks/:task_id Get a single task
PATCH  /projects/:id/tasks/:task_id Update task fields
DELETE /projects/:id/tasks/:task_id Delete a task
 
Response shape (GET /projects/:id):
{
  "id": "proj_abc123",
  "name": "Website Redesign",
  "status": "active",
  "created_at": "2026-03-01T10:00:00Z",
  "task_count": 12
}
 
Error responses:
404: { "error": "not_found", "message": "Project not found" }
403: { "error": "forbidden", "message": "Access denied" }
422: { "error": "validation_error", "fields": { "name": "required" } }

openapi: 3.1.0
info:
  title: Project Management API
  version: 1.0.0
 
paths:
  /projects:
    get:
      summary: List projects
      operationId: listProjects
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Paginated list of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'
    post:
      summary: Create project
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreate'
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
 
components:
  schemas:
    Project:
      type: object
      properties:
        id:
          type: string
          example: proj_abc123
        name:
          type: string
        status:
          type: string
          enum: [active, archived]
        created_at:
          type: string
          format: date-time

Review this list of API endpoints for inconsistencies in naming,
HTTP method usage, error response format, and pagination:
 
GET  /getUserById/:id
POST /create-task
GET  /tasks?user=:id
PUT  /task/:id/done
DELETE /remove-comment/:id

Inconsistencies found:
 
1. Naming: Mix of camelCase (/getUserById), kebab-case (/create-task),
   and verb-prefixed (/remove-comment). REST convention uses noun-based
   plural paths: /users/:id, /tasks, /comments/:id.
 
2. HTTP methods: PUT /task/:id/done should be PATCH /tasks/:id with
   body { "status": "done" }. Don't encode state in the URL.
 
3. Query parameter naming: ?user=:id should be ?user_id=:id for clarity.
 
4. Singular vs plural: /task/:id should be /tasks/:id (plural resources).
 
Recommended standardized routes:
GET    /users/:id
POST   /tasks
GET    /tasks?user_id=:id
PATCH  /tasks/:id
DELETE /comments/:id

from fastapi import APIRouter, HTTPException, Query
from pydantic import BaseModel
from typing import Optional
 
router = APIRouter(prefix="/projects", tags=["projects"])
 
class ProjectCreate(BaseModel):
    name: str
    description: Optional[str] = None
 
class ProjectResponse(BaseModel):
    id: str
    name: str
    description: Optional[str]
    status: str
    created_at: str
 
@router.get("", response_model=list[ProjectResponse])
async def list_projects(
    page: int = Query(1, ge=1),
    per_page: int = Query(20, ge=1, le=100),
):
    offset = (page - 1) * per_page
    # ... implementation
    return projects
 
@router.post("", response_model=ProjectResponse, status_code=201)
async def create_project(body: ProjectCreate):
    # ... implementation
    return project
 
@router.get("/{project_id}", response_model=ProjectResponse)
async def get_project(project_id: str):
    project = await db.get_project(project_id)
    if not project:
        raise HTTPException(status_code=404, detail="Project not found")
    return project