# OpenAPI Coverage

> Audience: vendor implementation team auditing the API surface before the Azure port.
> Companion to: [`openapi.json`](openapi.json), [`../README.md`](../README.md), [`../../docs/foundation/api-contract.md`](../../docs/foundation/api-contract.md).

This document records what the v1 OpenAPI spec covers today, what it deliberately excludes, and how the vendor should reason about the gap.

`npm run check:openapi` enforces structural correctness of the JSON spec. This file is descriptive — not enforced — and is meant to keep the spec ↔ route inventory honest.

---

## 1. Current coverage (matches v1 routes 1:1)

| Method(s)              | Path                       | Tag           | Notes                                                                                         |
| ---------------------- | -------------------------- | ------------- | --------------------------------------------------------------------------------------------- |
| GET                    | `/api/v1/health`           | Health        | Liveness + readiness signal. Open (no auth).                                                   |
| GET                    | `/api/v1/master-data`      | Master Data   | Reference values / lookup tables.                                                              |
| GET / POST             | `/api/v1/suppliers`        | Suppliers     | Supplier master data.                                                                          |
| GET / POST             | `/api/v1/projects`         | Projects      | Visit / project lifecycle list + create.                                                       |
| GET / PATCH / DELETE   | `/api/v1/projects/{id}`    | Projects      | Single visit/project.                                                                          |
| GET / POST             | `/api/v1/oee`              | OEE           | OEE records.                                                                                   |
| GET                    | `/api/v1/assignments`      | Assignments   | Consultant scheduling assignments.                                                             |

The route inventory (`find app/api/v1 -name route.ts`) returns exactly these 7 paths. Coverage of v1 is complete.

## 2. Out-of-scope routes (deliberate)

The `/api/admin/*`, `/api/owner/*`, `/api/demo/*`, `/api/planning/*`, `/api/wertstrom/*`, `/api/repository/*`, `/api/qaf-template`, `/api/projects/next-id`, `/api/holidays/seed`, and `/api/csp-report` paths are **not** part of v1. See [`../../docs/foundation/api-contract.md`](../../docs/foundation/api-contract.md) for the rationale.

The current route inventory (52 routes total):

| Surface             | Count | In v1 spec | Notes                                                                                              |
| ------------------- | ----: | ---------- | -------------------------------------------------------------------------------------------------- |
| `/api/v1/*`         |     7 | yes        | Public contract.                                                                                    |
| `/api/admin/*`      |    10 | no         | Tenant admin UI XHR. Coupled to admin permissions.                                                  |
| `/api/owner/*`      |    21 | no         | Owner / SaaS-operator portal. Owner-role auth.                                                      |
| `/api/demo/*`       |     3 | no         | Demo lifecycle. Should not be exposed externally.                                                  |
| `/api/planning/*`   |     3 | no         | Planning module XHR. Promote when stable.                                                           |
| `/api/wertstrom/*`  |     2 | no         | Value-stream-map module XHR. Promote when stable.                                                   |
| `/api/repository/*` |     1 | no         | Repository search XHR. Promote when stable.                                                         |
| Other               |     5 | no         | `csp-report`, `qaf-template`, `projects/next-id`, `holidays/seed`, etc.                            |
| **Total**           |    52 |            |                                                                                                    |

These numbers should match `find app/api -name route.ts | wc -l`. If they drift, this file or the route inventory is stale.

---

## 3. Why v1 stays narrow

- The v1 contract is the seam an external integrator (or a separate iOS / Android client) might rely on.
- Internal UI routes change with the UI; promoting them to v1 would force a breaking-change discipline on routes that are still moving.
- `/api/owner/*` uses owner-role auth, not tenant cookie auth. Mixing auth schemes in a single contract makes the spec messier, not cleaner.

The trade-off is that the OpenAPI does not give the vendor a single artefact for the entire HTTP surface. The `app/api/**/route.ts` inventory + this file are the alternative.

---

## 4. Recommendations for the vendor

| Decision                                                                                              | Recommendation                                                                                                                     |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Should v1 grow to cover internal routes?                                                              | Only after each route has had a stable shape for at least one release. Promotion is one-way.                                        |
| Should non-v1 routes be documented?                                                                    | Yes, but in a separate document (e.g. `INTERNAL_API.md`) — keep `openapi.json` to the public contract.                              |
| Is OpenAPI the right tool for the multi-platform port?                                                | Yes for v1. For internal routes, type-sharing through TypeScript is sufficient (current pattern).                                  |
| Should the vendor refactor `/api/v1/*` shapes?                                                         | No. v1 is the contract iOS / a future external integration is expected to consume. Refactor by adding `/api/v2/*` if needed.       |
| Should `/api/csp-report` be in v1?                                                                     | No — it is an unauthenticated browser-driven sink. It should remain unversioned.                                                    |

---

## 5. Maintenance

When a new route under `app/api/v1/` is added:
1. Add the path to `openapi.json` in the same PR.
2. Run `npm run check:openapi`. It enforces structural rules and the path-to-route mapping.
3. If the path is **not** under `/api/v1/`, do not add it here — promote it through the API contract workflow instead.

When the route inventory changes overall (new internal route, removed internal route), update the table in §2 so the counts stay honest.