Skip to content

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 — the same document as a real page, so you can compare rendering as well as source.

---
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`