This project provides common APIs for applications that live on VA.gov (formerly vets.gov APIs).

Build Status

VA.gov Platform Documentation

API Docs

For frontend, see vets-website.

1. Clone the vets-api repo:

   git clone https://github.com/department-of-veterans-affairs/vets-api.git

2. Set up key & cert for localhost authentication to ID.me:

   • Create a folder in your vets-api directory:

     mkdir config/certs
     touch config/certs/vetsgov-localhost.crt
     touch config/certs/vetsgov-localhost.key

   • Copy example configuration file:

     cp config/settings.local.yml.example config/settings.local.yml

   • Edit config/settings.local.yml to disable signed authentication requests:

     # settings.local.yml
     saml:
       authn_requests_signed: false

3. If you are developing features that need Sidekiq Enterprise, you must have access to the va.gov-team-sensitive repo and install the sidekiq enterprise license

   Sidekiq Enterprise is used for worker rate limiting and additional reliability in production and requires a license be configured on your development machine. If you do not have a license configured, the open source version of Sidekiq will be installed instead. This is not an issue unless you are specifically developing features that need Sidekiq Enterprise.

   DO NOT commit local Gemfile.lock modifications that remove the sidekiq-ent and sidekiq-pro gems.

4. Developers who work with vets-api daily tend to prefer the native setup because they don't have to deal with the abstraction of docker-compose while those who would to spend less time on getting started prefer the docker setup. Docker is also useful when it's necessary to have a setup as close to production as possible. Finally, it's possible to use a hybrid setup where you run vets-api natively, but run the Postgres and Redis dependencies in docker.

   • Native setup (OSX/Ubuntu)
   • Docker setup
   • Hybrid setup
   • Codespaces setup

• Running natively
• Running with Docker

Vets API is configured with Config. The default configuration is contained in settings.yml. To customize your setup, you can create a config/settings.local.yml file with configuration specific to your needs. For example, to configure Redis and PostgreSQL (PostGIS is required), place something like this in that file:

database_url: postgis://pg_host:9999/custom_db

redis:
  host: redis_host
  port: 9999

This is also where you will place any other customizations, such as API tokens or certificate paths.

Config settings that vary in value depending on the deployment environment will need to be set appropriately for each environment following these instructions. Secrets like keys, certs, and .pem files are stored in a different way. See these instructions.

The following features require additional configuration, click for details.

• Education Benefits
• EVSS
• Facilities Locator
• Local Network Access
• Mailers
• Master Person Index (MPI)
• My HealtheVet (MHV)
• Virtual Machine Access
• Test User Dashboard

To mock one or more of the above services see Betamocks

Vets API will still run in a limited capacity without configuring any of these features, and will run the unit tests successfully.

• Vets-api deployment is explained in this document
• The deploy status dashboard shows which environments a merged commit has been deployed to
• The latest deploys can also be seen at the links below:
  • dev: https://dev-api.va.gov/v0/status
  • staging: https://staging-api.va.gov/v0/status
  • sandbox: https://sandbox-api.va.gov/v0/status
  • prod: https://api.va.gov/v0/status

When sending HTTP requests use the X-Key-Inflection request header to specify which case your client wants to use. Valid cases are camel, dash, and snake. For example if you set X-Key-Inflection: camel then you can use camelCase keys in your JSON request body and you will get back data with camelCase keys in the response body. If the header is not provided then the server will expect snake_case keys in the request body and output snake_case in the response.

The version of Ruby and gem dependencies (including Rails) used are defined in the included Gemfile. The currently used versions of gems are maintained with Bundler and stored in the Gemfile.lock.

The goal is to have vets-api use supported versions of gems and Ruby, which is often the latest. However, for security reasons, we have a cool-down period so we don't update the gems immediately. If you need a newer version of a gem, please submit a pull-request.

• If you're on a VA.gov Platform team, contact your Program Manager.
• If you're on a VFS team, you must complete Platform Orientation to be added to this repository. This includes completing your Platform Orientation ticket(s) in GitHub.