transcription/docs/api_qa.md

# API Questions & Answers

## Question
```
what is v4_documents.py?
```

## Response
v4_documents.py is the new additive V4 API router I added in Phase 4.

What it does:
- Defines V4 endpoints under /api/v4 for registry-driven document/relationship workflows.
- Exposes read endpoints for catalogs:
  - GET /api/v4/document-types
  - GET /api/v4/person-roles
- Exposes write endpoints for code-or-id updates:
  - PUT /api/v4/documents/{document_id}/type
  - POST /api/v4/documents/{document_id}/people
  - PATCH /api/v4/document-people/{document_person_id}
  - DELETE /api/v4/document-people/{document_person_id}
- Uses DocumentService methods as the backend (no direct DB access in the route layer).
- Returns typed request/response models for backward-compatible, additive API evolution.

It is registered in app.py, so it is live when the app starts.

If you want, I can walk endpoint-by-endpoint with examples of request/response payloads.

---

## Question
```
Please do
```

## Response
Absolutely. Here is a quick endpoint-by-endpoint walkthrough of v4_documents.py, with practical request/response examples.

**What This Router Is**
- Prefix: /api/v4
- Purpose: additive V4 contract for:
1. Registry catalogs (document types, person roles)
2. Role-aware document-person linking
3. Code-or-id document type assignment
- It delegates to DocumentService and does not access DB sessions directly in route handlers.

**Dependency Wiring**
- Route dependency: get_document_service in v4_documents.py
- Behavior:
1. Uses app.state.services.documents when running in the app lifecycle
2. Falls back to a direct DocumentService() instance if needed (useful in isolated tests)

**1) List Document Types**
- Endpoint: GET /api/v4/document-types
- Query param: active_only=true by default
- Backing service call: list_document_types(active_only=...)
- Response shape:
[
  {
    "id": "uuid",
    "code": "letter",
    "label": "Letter",
    "is_active": true,
    "sort_order": 0
  }
]

**2) List Person Roles**
- Endpoint: GET /api/v4/person-roles
- Query param: active_only=true by default
- Backing service call: list_person_roles(active_only=...)
- Response shape:
[
  {
    "id": "uuid",
    "code": "author",
    "label": "Author",
    "is_active": true
  }
]

**3) Set Document Type (By Id Or Code)**
- Endpoint: PUT /api/v4/documents/{document_id}/type
- Body options:
1. document_type_id
2. document_type_code
- Rule: provide one selector, not both
- Example request:
{
  "document_type_code": "record"
}
- Example response:
{
  "document_id": "uuid",
  "document_type_id": "uuid",
  "document_type_code": "record"
}

**4) List Document-Person Links For A Document**
- Endpoint: GET /api/v4/documents/{document_id}/people
- Backing service call: list_document_people(document_id=...)
- Example response:
{
  "document_id": "uuid",
  "links": [
    {
      "id": "uuid",
      "document_id": "uuid",
      "person_id": "uuid",
      "role_id": "uuid",
      "role_code": "author",
      "person_name": "Zenna Cochran"
    }
  ]
}

**5) Add A Document-Person Link**
- Endpoint: POST /api/v4/documents/{document_id}/people
- Body fields:
1. person_id required
2. role_id optional
3. role_code optional
- If duplicate document/person/role link is attempted, returns conflict envelope via shared error handlers.
- Example request:
{
  "person_id": "uuid",
  "role_code": "mentioned"
}
- Example success response:
{
  "id": "uuid",
  "document_id": "uuid",
  "person_id": "uuid",
  "role_id": "uuid",
  "role_code": "mentioned",
  "person_name": "Ada Lovelace"
}

**6) Update Link Role**
- Endpoint: PATCH /api/v4/document-people/{document_person_id}
- Body options:
1. role_id
2. role_code
- Rule: provide one selector, not both
- Example request:
{
  "role_code": "recipient"
}
- Example response:
{
  "id": "uuid",
  "document_id": "uuid",
  "person_id": "uuid",
  "role_id": "uuid",
  "role_code": "recipient",
  "person_name": "Ada Lovelace"
}

**7) Delete Link**
- Endpoint: DELETE /api/v4/document-people/{document_person_id}
- Response: HTTP 204 No Content

**Error Behavior**
- Uses shared registration in errors.py
- So AppError categories map to consistent envelope + status codes:
1. validation_error -> 400
2. not_found_error -> 404
3. conflict_error -> 409
4. internal_unexpected_error -> 500

**Where It Gets Mounted**
- Included in app factory at app.py
- That makes all /api/v4 endpoints available during normal app startup.

If you want, next I can generate a compact curl-style smoke checklist for all 7 endpoints so you can test them in under 2 minutes.

---

## Question
```
Should there be one of these for people, jobs, and sources too?
```

## Response

Short answer: yes, but not all at once.

Given your V4 scope, the strongest split is:

1. Keep v4_documents.py for document-centric workflows  
This file already owns:
- document type catalog/use
- document-person role links
- document-level relationship mutations

2. Add a V4 people router next  
Recommended new file:
- src/transcription/api/v4_people.py

Why:
- You likely need person-centric queries and updates that are not naturally document-scoped
- It keeps API boundaries clearer as UI grows

3. Do not rush a separate jobs/sources V4 router unless contracts are diverging  
For now, jobs and sources are still tightly tied to the existing transcription pipeline behavior. A new v4_jobs or v4_sources router is useful only when you need genuinely new contract shape, such as:
- job lifecycle contract changes
- source revision/audit contract changes
- new pagination/filtering semantics incompatible with current endpoints

Practical rule of thumb:
1. New router if the domain has new V4 semantics and independent lifecycle
2. Keep existing router if only additive fields are needed

Suggested target structure:
1. v4_documents.py
2. src/transcription/api/v4_people.py
3. optional later: src/transcription/api/v4_jobs.py
4. optional later: src/transcription/api/v4_sources.py

If you want, I can scaffold v4_people next with additive endpoints that mirror your current service capabilities and keep error envelope behavior consistent.