Skip to content

Endpoints

SAIF.Agency.Api exposes ten endpoints across three controllers, one per resource: agencies, agents, and the appointments that connect them. Nine are reads; the only write is the agency contact update, and the only create is the appointment POST. Every route is an attribute route composed from the controller's [RoutePrefix] and the action's [Route], so the version segment v1 is part of the prefix rather than a header or a query parameter.

This page is the endpoint catalog and hub. Each controller's endpoints are documented in detail on its own page under endpoints/.

Route composition

Aspect Finding
Routing mode Attribute routes (MapHttpAttributeRoutes())
Convention template — (the default api/{controller}/{id} route is commented out in WebApiConfig.Register)
Versioning [RoutePrefix("v1/agencies")], [RoutePrefix("v1/agents")], [RoutePrefix("v1/appointments")]
Base path /agency (IIS virtual directory)

A resolved route is the controller's [RoutePrefix] followed by the action's [Route] fragment: [RoutePrefix("v1/agencies")] plus [Route("{agencyNumber}/agents")] gives GET /v1/agencies/{agencyNumber}/agents. An action whose [Route] is empty resolves to the prefix itself, which is how the search endpoint GET /v1/agencies is produced. Callers prepend the base path, so the absolute PROD address of that route is https://agencyapi.example.saif/agency/v1/agencies/{agencyNumber}/agents.

Controller catalog

Controller Route prefix Base Endpoints Documentation
AgenciesController v1/agencies AgencyApiBase 4 Details
AgentsController v1/agents AgencyApiBase 3 Details
AppointmentsController v1/appointments AgencyApiBase 3 Details

Endpoint catalog

Endpoint Controller Action Auth Success Errors Rules
GET /v1/agencies/{agencyNumber} AgenciesController GetAgency AgencyRead 200 OK 400, 404, 500 BR-001, BR-003
GET /v1/agencies AgenciesController SearchAgencies AgencyRead 200 OK 400, 500 BR-002, BR-003
GET /v1/agencies/{agencyNumber}/agents AgenciesController GetAgentsForAgency AgencyRead 200 OK 400, 404, 500 BR-001, BR-004
PUT /v1/agencies/{agencyNumber}/contact AgenciesController UpdateAgencyContact AgencyContactWrite 204 No Content 400, 404, 409, 500 BR-005, BR-006, BR-007, BR-008
GET /v1/agents/{agentNumber} AgentsController GetAgent AgencyRead 200 OK 400, 404, 500 BR-009
GET /v1/agents AgentsController SearchAgents AgencyRead 200 OK 400, 500 BR-009
GET /v1/agents/{agentNumber}/appointments AgentsController GetAppointmentsForAgent AgencyRead 200 OK 400, 404, 500 BR-010
GET /v1/appointments/{appointmentId} AppointmentsController GetAppointment None in code 200 OK 404, 500 —
GET /v1/appointments AppointmentsController SearchAppointments None in code 200 OK 400, 500 BR-003
POST /v1/appointments AppointmentsController CreateAppointment None in code 201 Created 400, 409, 500 BR-009, BR-010

AppointmentsController carries no authorization attribute at controller or action level, including on POST /v1/appointments, which creates a record. See Authentication and authorization for the consequence.

Request flow diagram

The following diagram visualizes how a request reaches a handling action.

flowchart TD
    REQ[Client request] --> ROUTE{Attribute route match}
    ROUTE -->|GET /v1/agencies/agencyNumber| GET1["AgenciesController.GetAgency"]
    ROUTE -->|GET /v1/agencies| GET2["AgenciesController.SearchAgencies"]
    ROUTE -->|GET /v1/agencies/agencyNumber/agents| GET3["AgenciesController.GetAgentsForAgency"]
    ROUTE -->|PUT /v1/agencies/agencyNumber/contact| PUT1["AgenciesController.UpdateAgencyContact"]
    ROUTE -->|No match| NF[404 Not Found]
    GET1 --> AUTH{SaifAuthorize role check}
    GET2 --> AUTH
    GET3 --> AUTH
    PUT1 --> AUTH
    AUTH -->|No| DENY[401 Unauthorized]
    AUTH -->|Yes| OP[AgencyService]
    OP --> OK[200 OK or 204 No Content]
    OP --> ERR[400, 404, or 409 via AgencyApiExceptionFilter]

Endpoints by operation

Endpoints that delegate to a documented processing workflow link to it here.

Endpoint Operation
PUT /v1/agencies/{agencyNumber}/contact OP-001

Sources

  • 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/Controllers/AgencyApiBase.cs