Skip to content

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

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