API application for Digital Marketplace.

• Python app, based on the Flask framework

This app provides an interface for our Postgres database backing service, using the SQLAlchemy ORM.

It's recommended to use the DM Runner tool, which will install and run the app (and a Postgres instance) as part of the full suite of apps.

If you want to run the app as a stand-alone process, you'll need to set the SQLALCHEMY_DATABASE_URI env variable to your own local Postgres instance. See the Developer Manual for more details.

You can then clone the repo and run:

make run-all

This command will install dependencies and start the app.

By default, the app will be served at http://127.0.0.1:5000.

Calls to the API require a valid bearer token. Tokens to be accepted can be set using the DM_AUTH_TOKENS environment variable (a colon-separated list), for example:

export DM_API_AUTH_TOKENS=myToken1:myToken2

If DM_API_AUTH_TOKENS is not explicitly set then the run script sets it to myToken. You should include a valid token in your request headers, for example:

curl -i -H "Authorization: Bearer myToken" 127.0.0.1:5000/services

POST requests will require a Content-Type header, set to application/json.

Run the full test suite:

make test

To only run the Python tests:

make test-unit

To run the flake8 linter:

make test-flake8

To re-create an empty test database without migrations (this is a useful troubleshooting step if you are having issues with the test database):

make test-bootstrap

The tests validate API responses against the model stubs in https://github.com/alphagov/digitalmarketplace-test-utils/tree/master/dmtestutils/api_model_stubs. To update these, point the API requirements-dev to a branch of digitalmarketplace-test-utils. Once your changes are approved in a PR you should make a new release of digitalmarketplace-test-utils and update the version in digitalmarketplace-api to use it.

requirements.txt file is generated from the requirements.in in order to pin versions of all nested dependencies. If requirements.in has been changed (or we want to update the unpinned nested dependencies) requirements.txt should be regenerated with

make freeze-requirements

requirements.txt should be committed alongside requirements.in changes.

After editing models.py to add/edit/remove models for the database, you'll need to generate a new migration script.

The easiest way to do this is to run

flask db migrate --rev-id <revision_id> -m '<description>'

Our revision IDs increment by 10 each time. Check the output of flask db show to find the current revision.

Until you apply the migration, you can delete the generated revision and re-generate it as you need to.

To apply new migrations:

make run-migrations

./scripts/list_migrations.py checks that there are no branches in the DB migrations and prints a list of migration versions.

flask routes prints a full list of registered application URLs with supported HTTP methods.

app/generate_model_schemas.py uses the alchemyjsonschema library to generate reference schemas of our database models.

Note that the alchemyjsonschema library is a dev requirement only.

This repository is maintained by the Digital Marketplace team at the Government Digital Service.

If you have a suggestion for improvement, please raise an issue on this repo.

If you have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner.

Please follow the GDS vulnerability reporting steps, giving details of any issue you find. Appropriate credit will be given to those reporting confirmed issues.

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.