This project provides common APIs for applications that live on VA.gov (formerly vets.gov APIs).
- Clone the
git clone https://github.com/department-of-veterans-affairs/vets-api.git
- Setup 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
config/settings.local.ymlto disable signed authentication requests:
# settings.local.yml saml: authn_requests_signed: false
- 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 modifications that remove the
- 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.
Running the app
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 also need to be set appropriately for each environment in the relevant devops (Private Repo) configurations (dev-, staging-, and prod-settings.local.yml.j2).
Some examples of configuration that will need to be added to these files are:
- API keys/tokens
- 3rd party service hostnames, ports, and certificates/keys.
- Betamocks settings
Optional application configuration
The following features require additional configuration, click for details.
- Authentication with ID.me
- Education Benefits
- Facilities Locator
- Local Network Access
- Master Veteran Index (MVI)
- My HealtheVet (MHV)
- Virtual Machine Access
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 upon each merge to
Each deploy is available here:
Additional deployment details can be found here:
API request key formatting
When sending HTTP requests use the
X-Key-Inflection request header to specify
which case your client wants to use. Valid cases are
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 goal is to have vets-api use supported versions of gems and Ruby, which is often the latest. However the versions are generally updated as need or availability arise. If you need a newer version of a gem, please submit a pull-request marked as
draft with just the gem updated and passing tests.