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.

REST API's

Alle nieuwe DSO-gebaseerde API's zijn te vinden onder het https://api.data.amsterdam.nl/v1/ endpoint. De individuele datasets worden toegelicht op de datasets pagina.

Beschikbare endpoints

De datasets ondersteunen de volgende HTTP operaties:

Verzoek Resultaat
GET /v1/{dataset}/{tabel}/ De lijst van alle records in een tabel
GET /v1/{dataset}/{tabel}/{id}/ Een individueel record uit de tabel

Bijvoorbeeld:

curl https://api.data.amsterdam.nl/v1/gebieden/buurten/
curl https://api.data.amsterdam.nl/v1/gebieden/buurten/03630000000092.1/

Wanneer een pagina direct met de browser opgevraagd wordt dan worden de resultaten als een doorklikbare HTML pagina getoond. Bijvoorbeeld: https://api.data.amsterdam.nl/v1/gebieden/buurten/. Door de header Accept: application/hal+json te sturen wordt altijd een JSON response geforceerd. Dit kan ook met de query parameter ?_format=json

Gebruik API Keys

Je kunt een sleutel verkrijgen via het online formulier. Geef deze sleutel bij iedere http-aanvraag met de X-Api-Key header mee, bijvoorbeeld:

curl https://api.data.amsterdam.nl/v1/gebieden/wijken/ -H "X-Api-Key: very...long...token".

Voor WFS/geo-tools die geen request headers ondersteunen is ook mogelijk om de queryparameter ?x-api-key=... te gebruiken.

Door de API key kunnen we contact houden met de gebruikers van onze API's. Zo kunnen we gebruikers informeren over updates, en inzicht krijgen in het gebruik van de API's. Voor data-eigenaren is dit waardevolle informatie.

Functionaliteit

De API's ondersteunen mogelijkheden tot:

De DSO Standaard

De API's op het /v1/ endpoint volgen de landelijke DSO standaard om een eenduidige wijze te bieden voor afnemers.

Hierdoor kom je als technisch gebruiker o.a. de volgende elementen tegen:

  • HAL-JSON links, zoals: {"_links": {"self": {"href": ..., "title": ...}}}
  • Met ?_expandScope={veld1},{veld2} worden relaties getoond in de _embedded sectie.
  • Met ?_expand=true worden alle relaties uitgevouwen in de _embedded sectie.
  • Met ?_fields=... kunnen een beperkte set van velden opgevraagd worden.
  • Sortering met ?_sort={veldnaam},-{desc veldnaam}
  • Filtering op velden via de query-string.
  • Tijdreizen met de ?geldigOp=... parameter.
  • Paginering en X-Pagination-* headers.
  • Geometrie projecties via de Accept-Crs header.
  • Responses geven het object terug, zonder envelope.