Skip to content

Example: API overview

overview.md explains what a REST API is for in business terms: which process it serves, which records it owns, who calls it, and what each capability does. Doc gen produces one per API at docs/apis/<api-slug>/overview.md.

What reviewers should check

  • ## Purpose is prose or bullets about business value. Hosting facts, target framework, and route configuration belong on the index page, not here.
  • Owning team and criticality are evidenced — a pipeline, a deployment definition, a telemetry owner such as ConfigureOpenTelemetry(o => o.Owner = "…"), or a code comment. Anything else reads "Not determined from source".
  • Every consumer in the table is backed by something in source or config: a generated client package, a using <ApiName>.Client; reference, a documented base-URL key, or a deployment definition. A plausible-sounding department name is not evidence.
  • The consumer table's endpoint links resolve to real anchors on the per-controller pages, and the endpoints named match what that consumer actually calls.
  • Base addresses record where each value came from. An environment row with no resolution source is a guess.
  • The capability summary covers every controller, and its endpoint links use the fully resolved routes rather than bare [Route] fragments.
  • ## Non-documented artifacts names the stock MVC scaffolding that was deliberately excluded, in one line, and is omitted entirely when there is none.

Example

The document below is a complete, correct api-overview.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: SAIF.Agency.Api overview
summary: Purpose, consumers, business context, and capability summary for the REST API.
status: draft
owner: Agency Systems Team
last_reviewed: 2026-09-10
---

# SAIF.Agency.Api overview

`SAIF.Agency.Api` publishes the agency distribution channel — agencies, the
agents who work at them, and the appointments that authorise those agents to
write business — to the applications that need it. It owns the `AGENCY` schema
and is the only service that writes agency contact details, so a change made
through this API is immediately visible to every consumer rather than being
replicated into local copies.

## Purpose
- Resolves an agency, its producer codes, and its servicing agents for
  applications that must attribute a claim, policy, or notice to a distribution
  partner.
- Maintains agency contact details — mailing address, contact email, and contact
  phone — as the single authoritative copy used for correspondence.
- Removes direct `AGENCY` schema access from consuming applications, so agency
  eligibility and status rules are enforced in one place.

## Business context

Every policy SAIF writes is placed through an appointed agency, and almost every
downstream process needs to know which one. Claims intake stamps the servicing
agency on a new claim so that correspondence and commission reporting are
correct; renewal notice generation resolves the servicing agent so the notice
carries a named contact; the agency portal reads and maintains the agency's own
contact details. If the service is unavailable, claims can still be entered but
without agency attribution, and the nightly renewal notice run fails to resolve
servicing agents and rejects the affected notices rather than mailing them to an
unknown recipient.

| Attribute | Value |
| --- | --- |
| Business domain | Agency distribution and appointment management |
| Owning team | Agency Systems Team (`ConfigureOpenTelemetry(o => o.Owner = "Agency Systems Team")` in `Global.asax.cs`) |
| Data ownership | Oracle `AGENCY` schema — `AGENCY`, `AGENCY_CONTACT`, `AGENCY_CONTACT_AUDIT`, `AGENT`, `AGENCY_APPOINTMENT` |
| Criticality | Tier 2 (`azure-pipelines.yml` deployment stage tag `criticality: tier-2`) |

## Consumers

| Consumer | Type | Endpoints used | Authentication | Notes |
| --- | --- | --- | --- | --- |
| Agency portal | Web application | [GET /v1/agencies/{agencyNumber}](endpoints/agencies.md#get-v1agenciesagencynumber), [GET /v1/agencies/{agencyNumber}/agents](endpoints/agencies.md#get-v1agenciesagencynumberagents), [PUT /v1/agencies/{agencyNumber}/contact](endpoints/agencies.md#put-v1agenciesagencynumbercontact) | Windows integrated, caller in `AgencyRead` and `AgencyContactWrite` | The only consumer that writes. Agency staff maintain their own contact details through the portal. |
| `SAIF.Claims.Intake` | Web application | [GET /v1/agencies](endpoints/agencies.md#get-v1agencies), [GET /v1/agencies/{agencyNumber}](endpoints/agencies.md#get-v1agenciesagencynumber) | Windows integrated, application pool identity in `AgencyRead` | Resolves the servicing agency from the producer code entered on the claim. |
| `SAIF.Policy.RenewalNotice` | Batch job | [GET /v1/agencies/{agencyNumber}](endpoints/agencies.md#get-v1agenciesagencynumber), [GET /v1/agencies/{agencyNumber}/agents](endpoints/agencies.md#get-v1agenciesagencynumberagents) | Windows integrated, scheduled task identity in `AgencyRead` | Calls through the `SAIF.Agency.Api.Client` package to name the servicing agent on each renewal notice. |

Both .NET consumers reference the generated `SAIF.Agency.Api.Client` package
rather than constructing requests by hand; the agency portal calls the service
directly from server-side controllers.

## Base address

| Environment | Base address | Resolved from |
| --- | --- | --- |
| DEV | `https://agencyapi-dev.example.saif/agency` | Environment API config key `AgencyApi.BaseUrl` |
| TEST | `https://agencyapi-test.example.saif/agency` | Environment API config key `AgencyApi.BaseUrl` |
| PROD | `https://agencyapi.example.saif/agency` | Environment API config key `AgencyApi.BaseUrl` |

## Capability summary

| Capability | Owning component | Endpoints | Description |
| --- | --- | --- | --- |
| Agency lookup | `AgenciesController` | [GET /v1/agencies/{agencyNumber}](endpoints/agencies.md#get-v1agenciesagencynumber) | Returns a single agency with its status, producer codes, and current contact details |
| Agency search | `AgenciesController` | [GET /v1/agencies](endpoints/agencies.md#get-v1agencies) | Returns agencies matching a producer code, optionally including terminated agencies |
| Agency roster | `AgenciesController` | [GET /v1/agencies/{agencyNumber}/agents](endpoints/agencies.md#get-v1agenciesagencynumberagents) | Returns the agents currently appointed at an agency |
| Contact maintenance | `AgenciesController` | [PUT /v1/agencies/{agencyNumber}/contact](endpoints/agencies.md#put-v1agenciesagencynumbercontact) | Replaces an agency's contact block and records the change for audit |
| Agent lookup and search | `AgentsController` | [GET /v1/agents/{agentNumber}](endpoints/agents.md#get-v1agentsagentnumber), [GET /v1/agents](endpoints/agents.md#get-v1agents) | Returns an individual agent or agents licensed in a given state |
| Appointment management | `AppointmentsController` | [GET /v1/appointments/{appointmentId}](endpoints/appointments.md#get-v1appointmentsappointmentid), [POST /v1/appointments](endpoints/appointments.md#post-v1appointments) | Reads and creates the appointment records that link an agent to an agency |

## Request and response format

| Aspect | Finding |
| --- | --- |
| Media types | JSON only — `config.Formatters.XmlFormatter` removed in `WebApiConfig.Register` |
| Serializer settings | camelCase property names (`CamelCasePropertyNamesContractResolver`), ISO-8601 dates with `DateTimeZoneHandling.Utc`, `NullValueHandling.Ignore` |
| Response envelope | DTOs returned directly; collection endpoints return a bare JSON array, not a wrapper object |

## Non-documented artifacts

- Stock Web API 2 project scaffolding — `Areas/HelpPage/`, `Views/Shared/Error.cshtml`, and `Content/Site.css` — is unmodified template output and is excluded from this document set.

## Related documentation
- [API index](index.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/Controllers/v1/AgenciesController.cs`
- `src/SAIF.Agency.Api/Controllers/v1/AgentsController.cs`
- `src/SAIF.Agency.Api/Controllers/v1/AppointmentsController.cs`
- `src/SAIF.Agency.Api/Web.config`
- `azure-pipelines.yml`