# Example: API index

`index.md` is the landing page for a single REST API's documentation set. Doc
gen produces one per API at `docs/apis/<api-slug>/index.md`: a fact table
describing how the service is hosted and routed, a map of every page in the set,
and a controller catalog that hands off to the per-controller endpoint pages.

## What reviewers should check

- Every row of the fact table is a finding taken from source. Routing mode, base
  controller, versioning, media types, and the composition root differ between
  repositories, so a row that reads like a framework default is a sign nobody
  opened `WebApiConfig.cs`.
- The composition root row names the file as it is spelled on disk, and the same
  path appears in Architecture → Composition root. A conventional path such as
  `App_Start\IoCConfig.cs` asserted without evidence is a defect.
- The documentation sections table lists only pages that were generated. A row
  pointing at `data-model.md` when the API has no persistence is a dead link.
- The controller table's endpoint counts match the number of H2 endpoint
  sections on each controller page, and each controller's route prefix is the
  `[RoutePrefix]` value, not a guess from the controller name.
- `## Embedded libraries` is present only when the repository really documents
  libraries; when it is omitted, the matching `Embedded libraries` line is also
  absent from `## Related documentation`.
- `## Related documentation` carries every sibling page except `index.md`
  itself, with conditional lines dropped only because the target was not
  generated — never for brevity.

## Example

The document below is a complete, correct `api-index.md` for a fictional API.

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

````markdown
---
title: REST API documentation
summary: Entry point for .NET Framework 4 ASP.NET Web API documentation.
status: draft
owner: Agency Systems Team
last_reviewed: 2026-09-10
---

# REST API documentation

`SAIF.Agency.Api` is the system of record for agency, agent, and appointment
data at SAIF. It exposes read endpoints that let internal applications resolve
which agency holds a producer code, which agents work there, and which of them
are appointed to write business, plus a single write endpoint that maintains
agency contact details. The agency portal, `SAIF.Claims.Intake`, and
`SAIF.Policy.RenewalNotice` all read from it rather than querying the `AGENCY`
schema directly, so agency data has one owner and one set of rules.

| Field | Value |
| --- | --- |
| **Service** | `SAIF.Agency.Api` |
| **Framework** | ASP.NET Web API 2 (`System.Web.Http`, .NET Framework 4.8) |
| **Host** | IIS — `Global.asax` + `AgencyApiApplication` : `System.Web.HttpApplication` |
| **Route configuration** | `App_Start\WebApiConfig.cs` → `Register(HttpConfiguration)` |
| **Routing mode** | Attribute routes (`MapHttpAttributeRoutes()`) — no convention route is registered |
| **Base controller** | `AgencyApiBase` : `ApiController` |
| **Versioning** | `[RoutePrefix("v1/agencies")]`, `[RoutePrefix("v1/agents")]`, `[RoutePrefix("v1/appointments")]` |
| **Media types** | JSON only — `config.Formatters.XmlFormatter` removed in `WebApiConfig.Register` |
| **Composition root** | `src\SAIF.Agency.Api\App_Start\AutofacConfig.cs` |

## Documentation sections

| Section | Description |
| --- | --- |
| [Overview](overview.md) | Purpose, consumers, business context, and capability summary |
| [Architecture](architecture.md) | Hosting, request pipeline, layering, and the DI composition root |
| [Endpoints](endpoints.md) | Endpoint catalog with per-controller detail pages |
| [Authentication and authorization](authentication-authorization.md) | Identity, authorization enforcement, and role requirements |
| [Dependencies](dependencies.md) | Libraries, packages, APIs, and database connections |
| [Configuration](configuration.md) | Environment API settings, runtime-resolved connections, Web.config surface |
| [Operations and processes](operations-processes.md) | End-to-end processing workflows behind the endpoints |
| [Business rules](business-rules.md) | Rules enforced during request processing |
| [Data model](data-model.md) | Persistence model, entity mappings, and stored procedure usage |
| [Operational runbook](operational-runbook.md) | Deployment, health checks, logs, status codes, error recovery |
| [Tech debt](tech-debt.md) | CRITICAL and HIGH severity findings |

## Controllers

| Controller | Route prefix | Endpoints | Documentation |
| --- | --- | --- | --- |
| `AgenciesController` | `v1/agencies` | 4 | [Docs](endpoints/agencies.md) |
| `AgentsController` | `v1/agents` | 3 | [Docs](endpoints/agents.md) |
| `AppointmentsController` | `v1/appointments` | 3 | [Docs](endpoints/appointments.md) |

## Related documentation
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Endpoints](endpoints.md)
- [Authentication and authorization](authentication-authorization.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Data model](data-model.md)
- [Operational runbook](operational-runbook.md)
- [Tech debt](tech-debt.md)

## Sources
- `src/SAIF.Agency.Api/Global.asax.cs`
- `src/SAIF.Agency.Api/App_Start/WebApiConfig.cs`
- `src/SAIF.Agency.Api/App_Start/AutofacConfig.cs`
- `src/SAIF.Agency.Api/Controllers/AgencyApiBase.cs`
- `src/SAIF.Agency.Api/Controllers/v1/AgenciesController.cs`
- `src/SAIF.Agency.Api/Controllers/v1/AgentsController.cs`
- `src/SAIF.Agency.Api/Controllers/v1/AppointmentsController.cs`
- `src/SAIF.Agency.Api/SAIF.Agency.Api.csproj`
````