This project provides common APIs for applications that live on VA.gov (formerly vets.gov APIs).
For frontend, see vets-website and vets-content repos.
See the native setup instructions if you can't use docker
To start, fetch this code:
git clone https://github.com/department-of-veterans-affairs/vets-api.git
- Install Docker for Mac. This will configure both
docker
anddocker-compose
. - Setup key & cert for localhost authentication to ID.me:
- Create a folder in your vets-api directory:
mkdir config/certs
- Create an empty key and cert:
touch config/certs/vetsgov-localhost.crt touch config/certs/vetsgov-localhost.key
- Create a folder in your vets-api directory:
- Disable signed authentication requests:
# settings.local.yml saml: authn_requests_signed: false
A Makefile provides shortcuts for interacting with the docker images. To run vets-api and its redis and postgres dependencies run the following command from within the repo you cloned in the above steps.
Sidekiq Enterprise is used for worker rate limiting and additional reliability. Sidekiq Enterprise requires a license be configured on your development machine. If you do not have license configured, Sidekiq Enterprise will simply not be installed during gem installation.
Unless you are sure you need a Sidekiq Enterprise feature, you are probably fine without configuring the license and running Sidekiq Enterprise. Normal Sidekiq will still be installed and run.
If you do need Sidekiq Enterprise, VA.gov Team Engineers can follow instructions here to install the enterprise license on their systems.
DO NOT commit Gemfile modifications that result from local builds without sidekiq enterprise if you do not have it enabled on your development system
make up
You should then be able to navigate to http://localhost:3000/v0/status in your browser and start interacting with the API. Changes to the source in your local directory will be reflected automatically via a docker volume mount, just as they would be when running rails directly.
The Makefile has shortcuts for many common development tasks. You can still run manual docker-compose commands, but the following tasks have been aliased to speed development:
make spec
- Run the entire test suite via the docker image (alias forrspec spec
). Test coverage statistics are incoverage/index.html
or in CodeClimatemake guard
- Run the guard test server that reruns your tests after files are saved. Useful for TDD!
make lint
- Run the full suite of linters on the codebase.make security
- Run the suite of security scanners on the codebase.make ci
- Run all build steps performed in CI.
make console
- Is an alias forrails console
, which runs an IRB like REPL in which all of the API's classes and environmental variables have been loaded.
To emulate a local install's workflow where you can run rspec
, rake
, or rails
commands
directly within the vets-api docker instance you can use the make bash
command.
$ make bash
Creating network "vetsapi_default" with the default driver
Creating vetsapi_postgres_1 ... done
Creating vetsapi_redis_1 ... done
# then run any command as you would locally e.g.
root@63aa89d76c17:/src/vets-api# rspec spec/requests/user_request_spec.rb:26
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
The following features require additional configuration, click for details.
- Authentication with ID.me
- EVSS
- Facilities Locator
- My HealtheVet (MHV)
- Education Benefits
- Master Veteran Index (MVI)
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.
Could not find %SOME_GEM_v0.0.1% in any of the sources
Run `bundle install` to install missing gems.
There is no need to run bundle install
on your system to resolve this.
A rebuild of the vets_api
image will update the gems. The vets_api
docker image
installs gems when the image is built, rather than mounting them into a container when
it is run. This means that any time gems are updated in the Gemfile or Gemfile.lock,
it may be necessary to rebuild the vets_api
image using the
following command:
make rebuild
- Rebuild thevets_api
image.
Jenkins deploys vets-api
upon each merge to master
:
http://jenkins.vfs.va.gov/job/department-of-veterans-affairs/job/vets-api/job/master/
Each deploy is available here:
https://dev-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 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.
There are many ways to contribute to this project:
Bugs
If you spot a bug, let us know! File a GitHub Issue for this project. When filing an issue add the following:
- Title: Sentence that summarizes the bug concisely
- Comment:
- The environment you experienced the bug (browser, browser version, kind of account any extensions enabled)
- The exact steps you took that triggered the bug. Steps 1, 2, 3, etc.
- The expected outcome
- The actual outcome (include screen shot or error logs)
- Label: Apply the label
bug
For security related bugs unfit for public viewing, email us feedback@va.gov
Code Submissions
This project logs all work needed and work being actively worked on via GitHub Issues. Submissions related to these are especially appreciated, but patches and additions outside of these are also great.
If you are working on something related to an existing GitHub Issue that already has an assignee, talk with them first (we don't want to waste your time). If there is no assignee, assign yourself (if you have permissions) or post a comment stating that you're working on it.
To work on your code submission, follow GitHub Flow:
- Branch or Fork
- Commit changes
- Submit Pull Request
- Discuss via Pull Request
- Pull Request gets approved or denied by core team member
If you're from the community, it may take one to two weeks to review your pull request. Teams work in one to two week sprints, so they need time to need add it to their time line.
If you have a question or comment about this project, file a GitHub Issue with
your question in the Title, any context in the Comment, and add the question
Label.