# Example: API client endpoint map

`endpoint-map.md` is the traceability page between a client and the API it
wraps: one row per remote member, naming the verb, the relative URL, and where
that endpoint is documented. Doc gen produces one per client at
`docs/clients/<client-slug>/endpoint-map.md`.

## What reviewers should check

- Every Endpoint cell takes one of exactly two forms: a link into
  `../../apis/<api-slug>/endpoints/<controller-slug>.md` when this run generated
  that API's documentation, or a backticked canonical API name marked `†` when
  the API lives in another repository. A bare route with neither fails the gate.
- Links resolve on disk. A link to an `apis/<slug>/` folder the run never
  produced is fabrication, not compliance — check the file and the anchor, not
  just the shape of the path.
- `## External API origin` is present only in the external case, and the
  local-link rows are deleted in that case. Both forms for the same API is a
  defect.
- Relative URL shows the expression the client composes — the template shape
  with its placeholders — not one worked example with a real agency number
  baked in.
- Every value in the Client member column also appears as an H2 in
  `reference.md`, and the Details link lands on that section.
- `## Coverage` reconciles: mapped rows plus unmapped rows equals the public
  member count. A member missing from both tables is a coverage failure.

## Example

The document below is a complete, correct `client-endpoint-map.md` for a
fictional API client package.

[View rendered example](rendered/clients/saif-agency-api-client/endpoint-map.md) — the same document as a real page, so you can compare rendering as well as source.

````markdown
---
title: Endpoint map
summary: Traceability from each client method to the API endpoint it calls.
status: draft
owner: Agency Systems Team
last_reviewed: 2026-09-10
---

# Endpoint map

This page traces every remote member of `IAgencyClient` to the `SAIF.Agency.Api` endpoint it calls. It is the page a reader uses to answer "which endpoint does this call hit, and where is that endpoint documented".

| Field | Value |
| --- | --- |
| **Wrapped API** | `SAIF.Agency.Api` |
| **Origin** | Documented by this run |
| **Base URL** | `<baseUrl>` — constructor argument, from the `AgencyApi.BaseUrl` app setting |
| **Version prefix** | `v1/` |
| **Remote members mapped** | 4 of 4 public members |

## Method to endpoint map

| Client member | Verb | Relative URL | Endpoint | Request DTO | Response DTO | Reference |
| --- | --- | --- | --- | --- | --- | --- |
| `GetAgency` | GET | `agencies/{agencyNumber}` | [`GET /v1/agencies/{agencyNumber}`](../../apis/saif-agency-api/endpoints/agencies.md#get-v1agenciesagencynumber) | — | `Agency` | [Details](reference.md#getagencystring) |
| `SearchAgencies` | GET | `agencies?producerCode={producerCode}&activeOnly={activeOnly}` | [`GET /v1/agencies`](../../apis/saif-agency-api/endpoints/agencies.md#get-v1agencies) | — | `AgencySummary` | [Details](reference.md#searchagenciesstring-bool) |
| `GetAgentsForAgency` | GET | `agencies/{agencyNumber}/agents` | [`GET /v1/agencies/{agencyNumber}/agents`](../../apis/saif-agency-api/endpoints/agencies.md#get-v1agenciesagencynumberagents) | — | `Agent` | [Details](reference.md#getagentsforagencystring) |
| `UpdateAgencyContact` | PUT | `agencies/{agencyNumber}/contact` | [`PUT /v1/agencies/{agencyNumber}/contact`](../../apis/saif-agency-api/endpoints/agencies.md#put-v1agenciesagencynumbercontact) | `AgencyContactUpdate` | `AgencyContact` | [Details](reference.md#updateagencycontactstring-agencycontactupdate) |

All four routes are served by `AgenciesController`, so every row resolves to the
same endpoint page. The API's other two controllers are not wrapped: this client
issues no request to the `v1/agents` routes on `AgentsController` or the
`v1/appointments` routes on `AppointmentsController`. A consumer that needs
appointment history calls the API directly.

Note that `GetAgentsForAgency` reaches agent data through the agencies
sub-resource, not through `AgentsController`. The distinction matters when
tracing a production incident from an IIS log back to a client member.

## Coverage

| Check | Result |
| --- | --- |
| Public members in `IAgencyClient` | 4 |
| Rows in the endpoint map | 4 |
| Rows in unmapped members | 0 |
| Every mapped row resolves or is †-marked | Yes |

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Package](package.md)
- [Client reference](reference.md)
- [Consumption](consumption.md)
- [Contracts](contracts.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

## Sources
- `src/SAIF.Agency.Api.Client/IAgencyClient.cs`
- `src/SAIF.Agency.Api.Client/AgencyClient.cs`
- `src/SAIF.Agency.Api/Controllers/AgenciesController.cs`
- `src/SAIF.Agency.Api/App_Start/WebApiConfig.cs`
````