Skip to content

Environments for developing APIs

VA recommends that API teams maintain a dedicated development environment along with a separate testing environment in order to support effective development and functional testing of their APIs.

Since APIs serve as interfaces intended for use by other development teams, VA strongly recommends that API teams provide a consumer integration non-production environment. This non-production environment allows API consumers to explore, evaluate, and integrate the API’s features in a controlled setting, supporting smoother onboarding and faster feedback cycles.

Details about these environments are described below.

Requirement

  • Create development and testing environments to support the API Team while developing, testing, and maintaining the API.
  • Data in non-production environments must not have personally identifiable information (PII) or protected health information (PHI).

Guidance

  • API consumers should use a consumer integration environment when exploring and evaluating an API.
  • Test data should be representative of actual data complexities found in the production data.

Development

The development environment is where software engineers merge their code as different pieces are built. This environment is typically introducing changes frequently and must not be a place where your API consumers access your API. This is a safe private space for software engineers to write and deploy code to test out new ideas and new logic for the API.

Testing

It is at the discretion of the API team on how their testing environment is utilized. It is often used for testing more complex business cases that require a more stable environment. The software update cadence to this environment is defined by the API team in order to efficiently accomplish their goals. It is typically updated once testing passes in the development environment.

Since API Teams often need this environment to solidify the quality of the code, it, therefore, should not be a place where your API consumers access your API. VA recommends a stable consumer integration environment for consumers to evaluate and explore the API.

Consumer integration

Guidance

  • API teams should provide a consumer integration environment to support the API consumers who want to explore, evaluate, and integrate the API’s features using a reliable environment.
  • API teams should provide consumers instructions on how to obtain credentials to access the API in the consumer integration environment.
  • Self-service sign up is preferred.

Requirement

  • Data in a consumer integration environment must not contain PII or PHI data.
  • API behavior in the consumer integration environment must match the API behavior in the production environment.

To enable ease of integration with VA partners, internal VA teams, and third party partners, VA recommends a consumer integration environment for consumers using VA APIs. To facilitate exploration of VA APIs, a prospective consumer should be able to sign up and obtain appropriate credentials to access the API. The API behavior in the consumer integration environment must match the production API behavior to avoid surprises when the consumer launches their application to production.

There are scenarios when the consumer integration environment may be slightly ahead of production functionality, but the time window of this should be short-lived to avoid a consumer building an application and expecting behavior in production that doesn't exist.

Production

The production environment is where the API interacts with real VA data that may contain PII and PHI data.

When releasing software updates to the API in the production environment, the software behavior in the consumer integration environment must be updated at the same time to maintain consistent behavior and not lag in functionality with production.

Consumer signup

VA APIs must follow the security standards. To access any VA API the appropriate credentials must be issued to the prospective API consumer. This requires a signup process to be available.

Consumer integration signup

Guidance

  • Sign up in the consumer integration environment should be immediate without team intervention.
  • Consumer credentials should be removed if consumer becomes inactive.

In the consumer integration environment, the consumer signup process should have a low barrier to entry to encourage rapid prototyping by prospective consumers. To support this, sign up should be immediate and fully automated, requiring no manual intervention from the API team or other support teams.

VA recommends an automated signup form the consumer completes with their name, organization, and contact information where an automated backend system assigns the credentials to the consumer, securely sends the credentials to the consumer, and then tracks their usage. Easily acquiring necessary credentials enables rapid prototyping and earlier time-to-production for application developers consuming the API.

Although this environment is only utilizing test data, inactive consumers should be removed in accordance with your program's policy on defining inactive consumers.

Production signup

Requirement

  • Sign up in the production environment must be monitored.
  • A consumer must demonstrate to the VA Stakeholders how the API will be used in production for APIs handling PII and PHI data.
  • Consumer credentials must be removed if consumer becomes inactive.

Consumer signup for production access must be monitored to ensure appropriate use of VA data. Prior to issuing production credentials to the first consumer outside of VA, ensure all necessary VA privacy paperwork is current for the API. For example, Directive 6508 for Privacy Threshold Analysis (PTA) and Privacy Impact Assessment (PIA), and System of Records Notice (SORN).

All non-VA consumers must be party to an agreement such as Terms of Service agreement, Memorandum of Understanding, or similar document that the Office of General Counsel approved. Please work with the Office of General Counsel and relevant privacy offices to determine requirements for your API.

To prevent unauthorized access through stale or unused credentials, access must be removed for inactive consumers. This is in accordance with VA Cyber-Security Program guidance under Directive 6500 for Security Continuous Monitoring and NIST guidance under NIST SP 800-53 Rev5:AC-02(03)-Disable Accounts. Inactivity is typically defined by your program policy. Industry best practices commonly use 90 days of inactivity to define an inactive consumer.