DSO-API’s Developer Documentation

This documentation gives an introduction behind the scenes of the DSO-API. For end-user documentation, see https://api.data.amsterdam.nl/v1/docs/.

A Brief Introduction

The DSO-API project was started by the Gemeente Amsterdam to create consistent API interfaces. Before DSO-API existed, each dataset had to be exposed by a standalone project. This caused inconsistencies and maintenance issues.

To solve that problem, the dataset definitions are decoupled from the code. The dataset definitions are written in an an extended JSON Schema definition (called “Amsterdam Schema”), which is loaded on startup. This way, all dataset are exposed in the same way.

Multiple datasets can be loaded in the same server instance. This turns the project into a central API-server, that hosts multiple datasets and even supports interlinking relations between the datasets.

Note

The name “DSO” comes from Digitaal Stelsel Omgevingswet and describes the design and guidelines for JSON-based API’s by government agencies in The Netherlands. Using this format, clients can to communicate with different JSON API’s in a generic and consistent manner.

Aside from REST endpoints, the datasets are also exposed as WFS and MVT (Mapbox Vector Tile) endpoints. The REST endpoints follow the DSO (Digitaal Stelsel Omgevingswet) guidelines. Most guidelines from DSO are based on the expired HAL-JSON API style.

Project Dependencies:

A simplified diagram of the main project dependencies:

Topics:

• Layers of Code
• REST Framework Intro
• Application Features
• Dynamic Models
• Dynamic API Endpoints
• Remote Endpoints
• Temporal Datasets
• Streaming Output
• Authentication & Authorization
• OpenAPI
• Dataset versioning
• WFS Server
• Environment Variables
• Standards Compliance

HOW-TO:

• Installation
• Managing requirements.txt
• Running Tests
• Schema Development
• OpenAPI Schema Testing
• Creating Azure AD Application for OAuth2 Authentication

API Documentation:

• dso_api.dynamic_api package
  • dso_api.dynamic_api.filterset module
  • dso_api.dynamic_api.openapi module
  • dso_api.dynamic_api.permissions module
  • dso_api.dynamic_api.remote package
  • dso_api.dynamic_api.routers module
  • dso_api.dynamic_api.serializers module
  • dso_api.dynamic_api.views package
• rest_framework_dso package
  • rest_framework_dso.crs module
  • rest_framework_dso.exceptions module
  • rest_framework_dso.fields module
  • rest_framework_dso.filters module
  • rest_framework_dso.openapi module
  • rest_framework_dso.pagination module
  • rest_framework_dso.parsers module
  • rest_framework_dso.renderers module
  • rest_framework_dso.response module
  • rest_framework_dso.serializer_helpers module
  • rest_framework_dso.serializers module
  • rest_framework_dso.views module
• schematools package
  • schematools.datasetcollection module
  • schematools.factories module
  • schematools.loaders module
  • schematools.naming module
  • schematools.types module
  • schematools.validation module
• schematools.contrib.django package
  • schematools.contrib.django.auth_backend module
  • schematools.contrib.django.db module
  • schematools.contrib.django.factories module
  • schematools.contrib.django.loaders module
  • schematools.contrib.django.managers module
  • schematools.contrib.django.models module
  • schematools.contrib.django.signals module