DSO API

A new generic API that exposes datasets. It uses the "Amsterdam Schema" to define the datasets, and exposes these in a DSO (Digitaal Stelsel Omgevingswet) compatible API. Part of that means that the API follows the HAL-JSON style.

Requirements

• Python >= 3.9
• Recommended: Docker/Docker Compose

Installation

Using Docker Compose (recommended for development)

Run docker compose:

    docker compose up

Navigate to localhost:8090.

By default a collection of example datasets is loaded, and a local database is setup and initialized. This behaviour can be changed with environment variables as described below.

Running tests inside the container can be done as follows:

    docker compose exec web pytest <file/dir>

Environment

The following environment variables are useful for configuring a local development environment.

• DATABASE_URL: the postgresql URL of the database the application should connect to. The default is the database container in the compose file.
• INITIALIZE_DB: Initialize the database with django migrate and import schema's. Default true.
• MOCK_DATA: Fill the initialized database with autogenerated mock data. Default: false.
• SCHEMA_URL: URL of the dataset schemas. To use the production schemas set this to: "https://schemas.data.amsterdam.nl/datasets/" Default is the schemas container in the compose file.
• DATASETS_INCLUDE: A comma separated lists of datasets to expose using the API or to generate mock data for. Default: None (expose all loaded datasets).
• DATASETS_INCLUDE: A comma separated lists of datasets to expose using the API or to generate mock data for. Default: None (expose all loaded datasets).

To connect to an authentication provider, set up the following environment variables:

• OAUTH_CLIENT_ID: The client id of the application
• OAUTH_JWKS_URL: The JWKS URL of the authentication provider.
• OAUTH_URL: The auth URL of the authentication provider.

Example

A local setup using the production dataset schema's with mock data:

    export INITIALIZE_DB=true
    export MOCK_DATA=true
    export DATASETS_LIST=bag,gebieden,brk_2,sport,precariobelasting
    export SCHEMA_URL="https://schemas.data.amsterdam.nl/datasets/"
    docker compose up

Debugging containerized code in VSCode

Run docker compose with the extra file.

    docker compose -f docker-compose.yml -f docker-compose.debug.yml up -d

In your .vscode folder, copy the launch.example.json to launch.json and the tasks.example.json to tasks.json. Ensure that the paths are matching with what you have (especially packages in your virtualenv).

Start the debugger through the Run and Debug menu. The debugger is called "Python Debugger: Remote Attach". You can now add breakpoints.

Note: this currently does not work with pytest in the container. It does work from the browser or through curl.

Without Docker Compose

See the instructions at: https://dso-api.readthedocs.io/en/latest/howto/install.html

These instructions can also be found in the dev-docs/source/howto/install.rst file.

End User Documentation

See: https://api.data.amsterdam.nl/v1/docs/ or the docs folder.