API Improvement Backlog

Owner: Backend Engineering Last reviewed: 2026-Q2

The API style guide in api-style-guide.md defines the target conventions. This page tracks known cleanup opportunities in the current API.

1. Path naming: mixed snake_case and kebab-case

• Older or root-index examples may still show snake_case names.
• Current stable routes should prefer kebab-case, such as /process-query, /doc-intel, and /action-points.
• Standardize on kebab-case (REST convention, already used by majority of routes)

2. Status codes: 200 for everything

• Some creates already use 201 Created, and notification read endpoints use 204 No Content.
• Audit remaining create/delete routes and align them with api-style-guide.md.

3. Pagination: only on documents endpoint

• /api/azure/documents uses limit/offset.
• /api/notifications uses cursor-style pagination.
• Some Kanban/comment lists are still unbounded because expected cardinality is small today.
• Identify which list endpoints need pagination
• Standardize response envelopes by pagination style.

4. Response models: some endpoints return inline dicts

• Most routes use Pydantic response_model — good
• Azure blob/upload endpoints (/api/azure/upload, /api/azure/download-url/{uuid}) return raw dicts
• Some webhook routes also lack explicit models
• Add Pydantic schemas for all endpoints so OpenAPI generation is complete

5. Plural vs singular in resource paths

• Plural: /api/kanban/boards, /api/kanban/action-points.
• Legacy singular/deprecated patterns may remain as compatibility wrappers.
• Convention is typically plural throughout: /boards, /boards/{id}
• Standardize on plural for both collections and individual resources

6. Sorting/ordering: no standard pattern

• No ?sort= or ?order= query parameters on any endpoint
• Ordering is hardcoded in queries
• Decide: document server-controlled ordering as intentional, or define a standard ?sort=field&order=asc|desc pattern before endpoints diverge

7. Unversioned API

• No /api/v1/ prefix, no version headers, no content negotiation.
• version="2.0.0" in FastAPI app config is for OpenAPI docs only.
• Document that the API is intentionally unversioned for now in api-style-guide.md.
• Define the trigger for introducing versioning (e.g., external consumers, breaking changes)