Skip to content

Consumer Communications

In addition to consumers contacting you, API teams must provide a way to communicate announcements with your consumers.

Requirement

  • API teams must inform consumers where and how to receive API announcements.
  • API teams must notify consumers of important events, such as outages, maintenance windows, enhancements, new versions, and deprecated versions.

Release Notes

All VA APIs must publish their release notes on CODE VA.

For public-facing APIs, release notes must be available on a public-facing location, in addition to CODE VA.

Notifications

Notifying consumers that a new release occurred or important events are occurring helps your consumers plan and support their applications.

  • API teams must provide consumers a place to sign up to receive outgoing announcements.
  • API teams must provide a location for their consumers to view the latest announcements. For public-facing APIs, this must be a public-facing location.

Events to communicate

API teams must communicate important events occurring in consumer-facing API environments, such as:

  • a widespread issue affecting API availability or service throughput
  • maintenance windows of when a service will be degraded or unavailable
  • a new major, minor, or patch version release along with release notes
  • a major version deprecation and guidance on what to use instead
  • deprecated functionality and guidance on what to use instead
  • resolution of a major outage or service degradation

Support expectations

Set expectations for the timeliness of consumer communications when you have important information for consumers. API teams should meet the following consumer Service Level Objectives:

Guidance

  • Announce a detected outage to all consumers within 15 minutes of detection.
  • Provide status updates on an outage or active incident every 60 minutes.
  • Report the API health status in a location accessible to your consumers.