Federal APIs are infrastructure
The U.S. federal government operates one of the largest API portfolios in the world. The IRS exposes filing APIs. The VA Lighthouse program publishes veteran benefit and health APIs. SAM.gov offers entity and contract data. data.gov catalogs thousands of agency datasets. The Treasury publishes fiscal data. CMS publishes Blue Button 2.0 health data. CDC publishes surveillance APIs. NIST publishes vulnerability data. These APIs are not optional features — they are the way federal systems compose with each other, with state and local governments, with industry, and with the public.
An API designed poorly becomes infrastructure debt that lasts decades. An API designed well becomes a multiplier for every downstream system that integrates with it. Precision Federal designs and builds federal APIs with that long horizon in mind, with explicit attention to USDS standards, OpenAPI specification rigor, federal authentication patterns, and gateway selection that fits the agency's authorization boundary.
USDS API standards as the federal baseline
The USDS API Standards (originally drafted by 18F, now maintained across the GSA TTS, USDS, and digital service teams) define the federal baseline:
- JSON over HTTPS — TLS 1.2 minimum, TLS 1.3 preferred. No HTTP, ever.
- Semantic versioning in the URL path (/v1, /v2) for breaking changes; backwards-compatible additions never bump the version.
- OpenAPI specification published alongside the API, kept in sync via CI verification.
- Consistent error responses using either RFC 7807 Problem Details or a documented agency error envelope.
- ISO 8601 timestamps with timezone, never localized strings.
- snake_case field names (the USDS preference; some agencies use camelCase — follow the agency style guide).
- Cursor or page-based pagination with explicit links rather than ad-hoc offset.
- CORS properly configured for browser-based consumers.
- Rate limiting with documented headers and 429 responses.
OpenAPI 3.1 as the contract
OpenAPI 3.1 is our default specification format for federal REST APIs. The shift from 3.0 to 3.1 matters for federal because 3.1 aligns with JSON Schema 2020-12 and supports webhooks (relevant for event-driven integrations). Practices we follow:
- Spec-first design. Write the OpenAPI document before any code. Review it with stakeholders. Generate server stubs and client SDKs from it.
- Contract testing. Schemathesis or Dredd run in CI to verify the implementation against the spec on every commit.
- Linting. Spectral with a federal ruleset — our ruleset enforces USDS standards, the agency style guide, and OpenAPI hygiene.
- Reference doc generation. Redocly, Stoplight Elements, or Swagger UI rendered as static documentation.
- SDK generation. openapi-generator producing typed Python, TypeScript, Go, and Java clients for downstream integrators.
REST, GraphQL, gRPC — choosing per use case
The default question is wrong. The right question is: per surface, what are the consumers and what are their constraints?
- REST — the right answer for public APIs, partner APIs, and any surface where the consumer base is broad and unknown. Maximum tooling, maximum cacheability, maximum readability for the developer who is encountering the API for the first time. Required for anything that will land on api.gov.
- GraphQL — the right answer when a single API serves many clients with divergent data needs, especially aggregator portals that compose multiple downstream services. The VA Lighthouse program and several agency veteran-facing portals use GraphQL. Comes with operational complexity (query cost analysis, persisted queries, schema federation) that must be planned for.
- gRPC — the right answer for internal service-to-service traffic inside a Kubernetes cluster or service mesh. Strongly typed via Protobuf, supports streaming, low latency. Not appropriate for browser clients or partner integrations because of tooling friction.
Most federal systems we design use REST at the perimeter and gRPC internally, with GraphQL appearing only when the citizen-facing aggregation pattern justifies it.
Federal API gateways
The gateway sits between the public internet (or partner network) and the agency service. It enforces authentication, applies rate limits, terminates TLS, mediates protocol differences, and emits logs to the SIEM. Gateway selection is constrained by the deployment substrate and the authorization boundary:
- AWS API Gateway — FedRAMP High in GovCloud. Tight integration with Lambda, IAM, WAF, Cognito. The default in AWS-native federal architectures.
- Apigee X — FedRAMP High. Strongest analytics and developer portal. Common in agencies with mature API programs.
- Kong Gateway — open source, Kubernetes-native, deploys cleanly on Platform One. Konnect is the SaaS control plane (FedRAMP authorization in progress as of recent updates).
- Azure API Management — FedRAMP High in Azure Government. Tight integration with Azure AD Government and Logic Apps.
- Tyk Gateway — open source, deploys on Kubernetes, gaining federal traction.
- Mulesoft Anypoint Government — FedRAMP, common in agencies with existing Mulesoft investment.
For new builds we typically recommend Kong on Kubernetes when the workload is on Platform One or on a multi-cloud Kubernetes substrate, AWS API Gateway when AWS-native, and Apigee when developer experience for external consumers is the dominant requirement.
Authentication patterns
Federal API authentication is not one decision; it is three concurrent decisions for three different consumer classes:
- Public / citizen-facing: Login.gov via OAuth2/OIDC. Login.gov is the GSA-operated federated identity provider for the public, FedRAMP High and IAL2/AAL2 capable.
- Partner / B2B: OAuth2 client credentials or authorization code flow against the agency identity provider. Short-lived JWT access tokens (15-60 minutes), longer-lived refresh tokens with strict rotation.
- Internal federal users: PIV/CAC certificate authentication, often brokered through the gateway and exchanged for short-lived JWT for downstream services.
Across all three: short-lived tokens, mTLS for service-to-service, every auth event logged to the SIEM, anomaly detection on token issuance.
Publishing to api.gov
api.gov is the federal API directory. Publishing puts an agency API in front of the developer ecosystem and signals that the API is intended for external use. Requirements include published documentation, a stable base URL, a contact for support, an OpenAPI specification, and ideally a developer portal with a try-it-now experience. We help agencies prepare the metadata, polish the developer-facing documentation, and operate the developer portal post-launch.
API versioning and deprecation
Federal APIs live for a long time. A deprecation that takes 6 months in industry takes 3 years in federal because downstream consumers include other agencies, state systems, and contractor systems with their own change cycles. We design for that: explicit deprecation policy published with the API, sunset headers (RFC 8594) on every response from a deprecated version, programmatic notice via the developer portal, and a documented migration guide before sunset.
Observability for federal APIs
Every API we build emits OpenTelemetry traces, structured logs (JSON), and Prometheus-format metrics. The four golden signals (latency, traffic, errors, saturation) feed dashboards and SLO calculations. See federal observability for the full pattern. Authentication and authorization events go to the agency SIEM. Per-consumer metrics (request count, error rate, latency) feed the developer portal so consumers can self-diagnose.
Who we build APIs for
- VA — Lighthouse-aligned APIs for benefits, health, and facilities.
- HHS — CMS Blue Button, FHIR APIs for health data.
- GSA — SAM.gov, USAspending.gov-aligned APIs.
- NIST — public datasets and NVD-aligned APIs.
- CDC — public health surveillance APIs.