This API provides access to Taric XML files that have been generated by the DIT Tariff Application.
Taric files are processed in sequential order so a client system knowing the last file that was imported could retrieve the next file in sequence.
Files are indexed by date to allow the respective file(s) for a particular date (typically yesterday) to be retrieved.
For example:
| DATE | FILE(S) |
|---|---|
| 20202-11-02 | 200000, 200001 |
| 20202-11-03 | 200002, 200003 |
| 20202-11-04 | 200004 |
| 20202-11-07 | 200005 |
/api/v1/taricdeltas/{date}
{date} defaults to yesterday
{date} must be in YYYY-MM-DD format
e.g.
curl localhost:8080/api/v1/taricdeltas
curl localhost:8080/api/v1/taricdeltas/2018-12-01
/api/v1/taricfiles/{sequenceid}
{sequenceid} is a 6 digit number
e.g.
curl localhost:8080/api/v1/taricfiles/18004
/api/v1/taricfiles/{sequenceid}
{sequenceid} is a 6 digit number
{file} as form element
e.g.
curl --form file=@/users/dave/downloads/Taric3_files/TGB18146.xml -H "X-API-KEY: def456" localhost:8080/api/v1/taricfiles/18146
The API is readable publicly without authentication.
An API key (X-API-KEY) is required to upload new files.
| NAME | PURPOSE |
|---|---|
| API_ROOT | URL prefix for serving files |
| TARIC_FILES_FOLDER | Location for Taric files (defaults to /) |
| TARIC_FILES_INDEX | Location of index file (defaults to /) |
| API_KEYS | Comma separated list of API keys that are SHA256 encoded |
| APIKEYS_UPLOAD | Same as API_KEYS above - except these are the keys authorised to upload Taric files |
| AWS_BUCKET_NAME | S3 bucket storing the Taric files *** |
| AWS_ACCESS_KEY_ID | S3 Access key |
| AWS_SECRET_ACCESS_KEY | S3 Secret |
** IP addresses can be a range such as 11.22.33.44/24
*** Storage can be S3 or local - depends on the module used in the build / import - either apifile.py or apifiles3.py
Virtualenv is recommended. pip-tools is used to manage live and dev dependencies.
$ virtualenv taric-api
$ source taric-api/bin/activate
(taric-api) $ pip install -r requirements-dev.txt
procfile and manifest.yml are provided
Using the Cloudfoundry cli:
cf push APP-NAME --no-start
cf set-env APP-NAME API_ROOT "https://APP-NAME.domain"
...
Edit requirements.in or requirements-dev.in and run the following:
$ make save-requirements
make check runs a suite of linting tools across the codebase. These checks are enforced through CI.
pre-commit is used to help spot problems before committing. Run pre-commit install --install-hooks to perform one-off setup of these hooks.
docker-compose.yml and a Dockerfile allow testing a containerised version locally.
Build the containers:
docker-compose build
docker-compose up
This will setup Minio for s3, a container for the tariff-api and another version, tariff-api-test that runs the tests. Tests are automatically run, to re-run them, restart the testing container:
docker-compose restart tariff-api-test
On making any code changes it will be desirable to rebuild the container.
The strategy is to use a Unix shell script and curl commands, compare the response codes.
tests/runtests.sh checks API response codes against expected. Note that the http header X-Forwarded-For is inserted for local testing. This should be removed when testing via a proxy or in a cloud environment.
tests/testserver.sh is a sample script to start a server locally with environment variables. tests/start-minio.sh and tests/stop-minio.sh control a MinIO server that is used for providing an S3-compliant backend for the API during tests.
You may wish to perform direct manual test against the application's endpoints
upon deploying to either of the
staging or
production environments. Example curls
against staging (replace `<api_key> with appropropriate values from the secrets store):
curl -H "X-API-KEY: <api_key>" https://tariffs-api-staging.london.cloudapps.digital/api/v1/taricfiles/200003
curl -H "X-API-KEY: <api_key>" --form file=@../migration/DIT210046.xml https://tariffs-api-staging.london.cloudapps.digital/api/v1/taricfiles/210046
curl -H "X-API-KEY: <api_key>" -X POST https://tariffs-api-staging.london.cloudapps.digital/api/v1/rebuildindex
Integration tests may be executed against services instance by creating and
configuring a .env file in the /test_integration directory and then
executing them via pytest:
pytest --env-file=.env test_integration
See the file /test_integration/example.env for an example .env file.
Multiple .env files may be configured in this way to allow pointing at
different .env files, each containing settings for its specific service
instance.
Note that because tests may have enduring side-effects (if one of the tests fails), they probably shouldn't be run against a production service.
The complete API specification is documented and available in separate word documentation.