Skip to content

Example: API client package index

index.md is the entry point for an API client package's documentation set. Doc gen produces one per client at docs/clients/<client-slug>/index.md, naming the package, the API it wraps, and every other page in the set.

What reviewers should check

  • The output path is docs/clients/<client-slug>/ regardless of whether the client ships from its own repository or alongside the API it wraps. A reader's path that mirrors repository layout is a defect.
  • The identity table names the client class and the interface it implements (AgencyClient : IAgencyClient), not just the package id, and the HTTP surface row says SAIF.Web.API.Clients.JsonHttpClient.
  • The ## Wrapped API table is honest about origin: when the run generated docs/apis/<api-slug>/, the API documentation row is a link that resolves on disk; when it did not, the row is a backticked canonical name marked †. A fabricated link to an apis/ folder this run never produced is a blocker.
  • Base URI source names the concrete mechanism — a config key, a constructor argument, or "caller-supplied" — not the word "configuration".
  • The ## Documentation sections table and the ## Related documentation list agree with each other and with the files that actually exist; the conditional Business rules row appears in both or in neither.
  • ## Related documentation is the complete sibling set minus index.md itself, using the canonical document names (Package, Client reference, Endpoint map, Consumption), never invented labels.

Example

The document below is a complete, correct client-index.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: API client package documentation
summary: Entry point for .NET Framework 4 API client package documentation.
status: draft
owner: Agency Systems Team
last_reviewed: 2026-09-10
---

# API client package documentation

`SAIF.Agency.Api.Client` is the supported way for internal .NET Framework
applications to read agency, agent, and appointment data from `SAIF.Agency.Api`.
It wraps the `v1/agencies` routes behind a four-member interface, hides URL
composition and JSON deserialization behind `JsonHttpClient`, and ships the
shared `SAIF.Agency.Api.Core` contracts so that callers bind to the same DTOs
the API returns. `SAIF.Claims.Intake`, `SAIF.Policy.RenewalNotice`, and the
agency portal all consume it rather than issuing their own HTTP calls.

| Field | Value |
| --- | --- |
| **Package id** | `SAIF.Agency.Api.Client` |
| **Assembly** | `SAIF.Agency.Api.Client.dll` |
| **Framework** | .NET Framework 4.8 (`lib\net48`) |
| **Client class** | `AgencyClient` : `IAgencyClient` |
| **HTTP surface** | `SAIF.Web.API.Clients.JsonHttpClient` |
| **Wrapped API** | `SAIF.Agency.Api` |
| **Shared contracts** | `SAIF.Agency.Api.Core` |

## Documentation sections

| Section | Description |
| --- | --- |
| [Overview](overview.md) | What the client wraps, who consumes it, and capability summary |
| [Architecture](architecture.md) | Internal structure, `JsonHttpClient` wrapping, and construction |
| [Package](package.md) | nuspec identity, version, dependencies, shipped content, feed, and pipeline |
| [Client reference](reference.md) | One section per public member of the client interface |
| [Endpoint map](endpoint-map.md) | Client method → API endpoint traceability |
| [Consumption](consumption.md) | How a consumer constructs and calls the client |
| [Contracts](contracts.md) | The shared DTO/contracts assembly |
| [Dependencies](dependencies.md) | Packages, framework components, and the wrapped API |
| [Business rules](business-rules.md) | Rules enforced client-side before or after the call |
| [Tech debt](tech-debt.md) | CRITICAL and HIGH severity findings |

## Wrapped API

| Attribute | Value |
| --- | --- |
| API name | `SAIF.Agency.Api` |
| Documented by this run | Yes |
| API documentation | [SAIF.Agency.Api](../../apis/saif-agency-api/index.md) |
| Base URI source | Constructor argument; consumers pass the `AgencyApi.BaseUrl` app setting |
| Version suffix | `v1/` |

## Related documentation
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Package](package.md)
- [Client reference](reference.md)
- [Endpoint map](endpoint-map.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/AgencyClient.cs`
- `src/SAIF.Agency.Api.Client/IAgencyClient.cs`
- `src/SAIF.Agency.Api.Client/SAIF.Agency.Api.Client.csproj`
- `scripts/SAIF.Agency.Api.Client/SAIF.Agency.Api.Client.nuspec`