Quickstart

Installation

Pre-requisites

  • Python 3.10 or higher

  • Setuptools 30.3.0 or higher

  • Only the PostgreSQL database is supported

Install from PyPI

Install from PyPI with pip:

pip install vng-api-common

Configure the Django settings

  1. Add vng_api_common to INSTALLED_APPS, with the rest of the dependencies:

    INSTALLED_APPS = [
    ...,
    'django_filters',
    'vng_api_common',
    'vng_api_common.authorizations',
    'vng_api_common.notifications',  # optional
    'vng_api_common.audittrails',  # optional
    'drf_spectacular',
    'rest_framework',
    'rest_framework_gis',
    'solo',  # required for authorizations and notifications
    ...
]

  2. Add the required middleware:

     1 MIDDLEWARE = [
 2     'django.middleware.security.SecurityMiddleware',
 3     'django.contrib.sessions.middleware.SessionMiddleware',
 4     'django.middleware.common.CommonMiddleware',
 5     'django.middleware.csrf.CsrfViewMiddleware',
 6     'django.contrib.auth.middleware.AuthenticationMiddleware',
 7     'vng_api_common.authorizations.middleware.AuthMiddleware',
 8     'django.contrib.messages.middleware.MessageMiddleware',
 9     'django.middleware.clickjacking.XFrameOptionsMiddleware',
10     'vng_api_common.middleware.APIVersionHeaderMiddleware',
11 ]

  3. Add the default API settings:

    from vng_api_common.conf.api import *  # noqa

...

    Imports are white-listed in the shipped settings module, so it’s actually safe to do import * ;)

  4. See vng_api_common/conf/api.py for a list of available settings.

  5. The SITE_DOMAIN setting must be explicitly defined in your settings or set using an environment variable,

    as it is used to defines the main domain of the site.

Usage

API Spec generation

To generate the API spec, run:

generate_schema

This will output:

  • src/openapi.yaml: the OAS 3 specification

See the reference implementations of ZRC, DRC, BRC en ZTC to see it in action.

Run-time functionality

See the rest of the documentation for the available modules and packages.