Het Dataplatform van gemeente Amsterdam gaat het gebruik van een API key bij het gebruik van API's verplicht stellen. Hiermee wil het Dataplatform inzicht krijgen wie gebruik maakt van haar APIs, zodat het Dataplatform kan communiceren over updates en wijzigingen in de API's. Eventuele wijzigingen in de API's kunnen dan tijdig geïmplementeerd worden in uw systemen. Dit gaat gelden voor alle zogenaamde 'DSO API's' van het Dataplatform van gemeente Amsterdam.

Het gebruik van een API key bij de aanroep van een API van het Dataplatform van gemeente Amsterdam is vanaf half september optioneel. In overleg met de dataorganisatie wordt een deadline vastgesteld voor het moment vanaf wanneer de API keys verplicht worden. U kunt de API's van het Dataplatform dan niet meer gebruiken zonder een API key mee te geven.

Dit heeft gevolgen voor uw systemen!

Vraag tijdig een API key aan om uw systemen hierop aan te passen. U kunt met dit formulier een API key aanvragen.

Autorisatie

Veel van de REST API endpoints zijn anoniem toegankelijk. Echter, voor sommige endpoints is autorisatie nodig. Deze autorisatie vindt plaats mbv. een JSON Web Token (JWT).

Per dataset is aangegeven of deze openbaar is, of dat er een of meer zgn. autorisatiescopes van toepassing zijn.

Deze scope kan gelden voor de volledige dataset, voor een of meer tabellen binnen de dataset of voor individuele velden van een tabel. Als een dataset of tabel is beschermd met een scope die niet aanwezig is in het JWT, dan geven requests op die dataset/tabel een error 403 (Forbidden). Als alleen een veld zodanig is beschermd, dan wordt het request uitgevoerd als gewoonlijk maar verschijnt het beschermde veld niet in het resultaat. Er verschijnt ook geen melding over velden die om deze reden niet aanwezig zijn. Bij twijfel moet het resultaat van een request naast het betreffende schema worden gelegd om te zien welke velden ontbreken en waarom.

Bestaande scopes

De scopes zijn gedefineerd op https://github.com/Amsterdam/amsterdam-schema/tree/master/scopes. Bekende scopes zijn:

  • FP/MDW: Deze scope heeft elke ingelogde medewerker van de gemeente Amsterdam.
  • FP/WAGENPARK: Dit functieprofiel geeft toegang tot de dataset met info over het wagenpark.
  • FP/STURINGSMIDDELEN: Dit functieprofiel geeft toegang tot financiele gegevens uit de administratie van de gemeente Amsterdam.
  • BRK/RO: Deze scope geeft toegang tot kadastrale objecten.
  • BRK/RS: Deze scope geeft de rechten van BRK/RO en bovendien toegang tot niet natuurlijke subjecten.
  • BRK/RSN: Deze scope geeft de rechten van BRK/RS en bovendien toegang tot natuurlijke subjecten.

Toekenning van deze scopes kan worden aangevraagd bij de afdeling IV Beheer.

Om de API te testen met autorisatie kan de Swagger UI worden gebruikt. Deze is te vinden op:

https://api.data.amsterdam.nl/v1/<dataset-id>

Bij klikken op Authorize wordt het JWT token gezet voor gebruik in de Swagger UI. Bovendien wordt het token ook gepresenteerd in het scherm, zodat het kan worden gekopieerd om bijv. als volgt met curl te gebruiken:

curl https://api.data.amstdam.nl/v1/<dataset>/<table>/...
    --header "Authorization: Bearer ${token}"