General Guidelines

This section outlines the general guidelines for the architecture and documentation standards that all APIs at VA should follow.

Recommendations follow established industry API standards. While developing APIs for the Department of Veterans Affairs (VA) and the government presents unique challenges, API teams can leverage existing API guidelines refined in the open-source community and the private sector.

Not all consumers of VA APIs will be familiar with the VA API landscape. Following industry standards and best practices will ensure that VA APIs share a common interface and behave similarly to best-of-breed APIs outside VA.

Using these standards when developing reduces the research that teams typically do before starting and lets developers access the more in-depth, industry-standard documentation elsewhere when necessary.

In this section:

• API-first: Create an API contract before beginning development.
• Architecture: REST as the architectural style is prescribed for distributed systems.
• Data interchange: JSON is the recommended format for API request and response payloads.
• Documentation: Document the API in a format both humans and computers understand.
• Development process: Development approach for building APIs.
• Development environments: Development environments for successful delivery of APIs.
• Test data: Requirements and best practices for test data.
• Performance & Availability: Expectations for APIs in the consumer integration and production environments.