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.

Paginering

De REST API geeft de resultaten gepagineerd terug. De paginagrootte kan aangepast worden door een ?_pageSize={n} query parameter toe te voegen aan de request URL.

In de response zijn de volgende elementen te vinden:

{
    "_links": {
        "self": {
            "href": "https://api.data.amsterdam.nl/v1/gebieden/buurten/"
        },
        "next": {
            "href": "https://api.data.amsterdam.nl/v1/gebieden/buurten/?page=3"
        },
        "previous": {
            "href": "https://api.data.amsterdam.nl/v1/gebieden/buurten/?page=1"
        }
    },
    "_embedded": {

       // alle objecten...

    },
    "page": {
        "number": 2,
        "size": 20
    }
}

Met de velden _links.next en _links.previous zijn respectievelijk de volgende en vorige pagina op te vragen. Meer algemeen kan pagina n worden opgevraagd met ?page={n}. Paginanummers beginnen bij één, niet nul. De links next en previous ontbreken op de laatste, resp. eerste, pagina.

In het object page zijn de volgende velden opgenomen:

• page.number: het huidige paginanummer;
• page.size: de grootte van een pagina.

Wordt ?_count=true meegegeven, dat bevat het tevens:

• page.totalElements: het aantal objecten in de (gefilterde) resultaatset;
• page.totalPages: het aantal pagina's dat de resultaatset beslaat.

Bijvoorbeeld:

"page": {
    "number": 1,
    "size": 20,
    "totalElements": 117,
    "totalPages": 6,
}

Het tellen van resultaten moet expliciet aangevraagd worden omdat dit bij grote datasets vertragend werkt. Lees _links.next uit om te zien of er een volgende pagina is.

De velden uit het page-object worden ook als HTTP-headers in de response teruggegeven:

• X-Pagination-Page: Het huidige paginanummer.
• X-Pagination-Limit: de grootte van een pagina.
• X-Total-Count: de grootte van de resultaatset.
• X-Pagination-Count: het aantal paginas voor de gegeven _pageSize.

De laatste twee zijn weer alleen aanwezig in het geval _count=true.