API eigenschappen

Onze API’s worden geleverd als een REST-service. Nieuwe resources worden toegevoegd zonder kennisgeving. Resources worden 6 maanden voor verwijdering deprecated en de technisch contactpersoon die is geregistreerd in Ons API Dashboard wordt op de hoogte gebracht van de verwijdering.

Deze pagina legt de algemene werking en het gedrag van onze API’s uit. De lijst met beschikbare API’s en hun documentatie is hier te vinden.

URL’s en omgevingen

Er bestaan drie soorten omgevingen, met een eigen URL.

omgeving	gebruik	URL
DEVELOPMENT	Ontwikkelen van de connector met gebruik van ficitieve data	`https://api-development.ons.io`
STAGING	Testen van de connector op een staging-omgeving van een zorgorganisatie	`https://api-staging.ons.io`
PRODUCTION	De connector gebruiken op een productie-omgeving van een zorgorganisatie	`https://api.ons.io`

Pad en context

Alle endpoints beginnen met het basispad /t/, met uitzondering van het /ping endpoint.

Voorbeeld
Het pad voor het /clients/{id} endpoint op development is: api-development.ons.io/t/clients/3.

HTTP Methods

Ons API ondersteunt de REST-architectuur op basis van de HTML-methoden: GET, POST, PUT, DELETE.

GET

Wordt gebruikt om resources en gerelateerde data op te halen. Queryparameters worden gebruikt om een sub-set te selecteren of een soort filtering toe te passen. Queryparameters zijn bijna altijd optioneel. Requests veranderen de serverstatus niet. Veelvoorkomende URL’s zijn onder andere:

Formaat	Gebruik
`/resource`	vraagt alle entries op
`/resource/42`	vraagt specifieke entry op
`/resource/42/sub_resource`	vraagt alle entries op die gerelateerd zijn aan een entry
`/resource/x-stream-connect/data`	vraagt alle entries op in een streamende aangelegenheid

POST

Wordt gebruikt om nieuwe resources te creëren of een soort actie uit te voeren. POST-requests worden ook gebruikt wanneer gevoelige gegevens worden overgedragen (zoals bij een login). Voor een retourstatus 200 wordt dezelfde bron teruggegeven met enkele bijgewerkte velden. Verzoeken veranderen de server state.

Formaat	Gebruik
`/resource`	creëert een nieuwe resource
`/resource/42/sub_resource`	creëert een nieuwe sub-resource voor resource
`/resource/42/action`	voert actie uit voor resource

PUT

Wordt gebruikt om een bestaande resource te wijzigen. Het gedrag van POST is ook van toepassing op PUT.

Formaat	Gebruik
`/resource/42`	wijzigt resource

DELETE

Verijwdert een specifieke resource of verwijdert een relatie tussen resources.

Formaat	Gebruik
`/resource/42`	verwijdert resource

Headers

Het is mogelijk om headers toe te voegen aan HTTP requests op Ons API. Er zijn drie headers die van belang zijn:

Accept

Deze header is vereist en definieert het teruggegeven formaat. Sommige API’s geven octet-streams (bytes) terug en /ping geeft ‘text/plain’ terug. Als een formaat wordt aangevraagd wat niet gegeven kan worden, ontvang je statuscode 406. Je kunt meerdere formaten invoeren, waarbij het eerstgenoemde formaat de voorkeur krijgt. Weights moeten ook worden ondersteund. Applicaties die het content-type niet specificeren in hun Accept-header zullen JSON ontvangen.

Accept: application/json

Vanaf medio 2024 wordt alleen nog JSON ondersteund en dus geen XML, zelfs niet als dit expliciet is opgevraagd.

Content-Type

Deze header is vereist voor POST en PUT calls. Deze header geeft het formaat aan dat wordt gebruikt in de HTTP body. Er is er slechts één mogelijk. De tekenreeksenset (charset) is optioneel maar aanbevolen.

Content-Type: application/json

User-Agent

Deze header is optioneel maar het helpt ons (Nedap) bij het identificeren van requests als er problemen zijn.

User-Agent: connector/1.1+http://your-domain.com

waarbij connector vervangen zal moeten worden door de naam van de gebruikte connector.

HTTP Response codes

Ondestaande tabel geeft informatie over te verwachten HTTP response codes.

Status	Tekst	Omschrijving
200	OK	GET: geldige respons met de opgevraagde data in de response body. POST/PUT: geldige respons met de opgegeven resource, verrijkt met aanvullende informatie in de response body.
201	Created	POST: object aangemaakt, respons heeft geen body. Er bestaat een Location header waarin een pad staat waar de resource gevonden kan worden.
202	Accepted	PUT: wijzigingen zijn geaccepteerd, geen response body
204	No Content	POST: gebruikt voor acties die succesvol zijn. GET: resource die is opgevraagd had geen content.
304	Not Modified	GET: opgevraagde resource is niet gewijzigd sinds het moment dat deze de laatste keer is opgevraagd.
400	Bad request	GET: de combinatie vn queryparameters is ongeldig. POST/PUT: de gegeven content is incorrect. Je ontvangt een ErrorResponse body met een indicatie wat er verkeerd is.
401	Unauthorized	Er zijn te weinig / geen juiste rechten om de resource te benaderen.
402	Payment required	Gereserveerd voor toekomstig gebruik.
403	Forbidden	Authenticatie niet geslaagd.
404	Not found	De opgevraagde resource is niet gevonden.
406	Not acceptable	Verkeerde accept header.
409	Conflict	POST: De gegeven resoure bestaat al of is gewijzigd door een andere call.
410	Gone	De opgevraagde resource is niet meer beschikbaar op het opgegeven adres.
423	Locked	GET: De aangeboden resource is nog niet gereed. Dit gebeurt bij vertraagde jobs die tijd nodig hebben om verwerkt te worden.
429	Too many requests	De rate limiter is ingeschakeld, omdat de maximale waarde wordt overschreden.
495	Invalid certificate	Het SSL-certificaat is ongeldid. Deze is mogelijk verlopen, of is niet getekend door de correcte certificate authority.
500	Internal server error	Er is een fout aan de zijde van Nedap. Wij hebben zeer waarschijnlijk een automatische melding ontvangen, maar willen je ook verzoeken om een ticket bij onze supportafdeling aan te maken.
502	Bad gateway	Ongeldige upstreams. Dit gebeurt tijdens updates van achterliggende Nedap-systemen (meestal op dinsdagavonden).
503	Service unavailable	Een service is niet beschikbaar. Dit gebeurt tijdens updates van achterliggende Nedap-systemen (meestal op dinsdagavonden).
504	Gateway timeout	Er is een timeout opgetreden in de infrastructuur van Nedap of van de supplier (jij). Dit kan gebeuren tijdens updates (meestal op dinsdagavonden) of wanneer er een verstoring in het netwerk van Nedap of supplier (jij) is.

Rate limiting

Requests worden gelimiteerd om te voorkomen dat connectors inefficiënte API’s gebruiken voor hun use-cases. De gehandhaafde limieten zijn ruime waardes en zouden in de praktijk niet bereikt moeten worden tijdens correct gebruik van de API’s. Requests worden als volgt gelimiteerd:

4 requests tegelijkertijd (parallel) per certificaat
100 requests per seconde (momenteel niet afgedwongen)
10.000 seconden die requests totaal per dag in beslagen nemen (momenteel niet afgedwongen)

Toelichting

De laatstgenoemde limiet wordt gemeten als een som voor alle uitgevoerde requests. Dit kunnen bijvoorbeeld 100.000 requests zijn die elk 100 milliseconden duren, of 1 request dat 10.000 seconden duurt.

Op dit moment wordt alleen de gelijktijdige verbindingslimiet gehandhaafd. In de toekomst kunnen we ook de andere limieten handhaven. We zullen echter eerst onderzoeken of connectors hierdoor worden beïnvloed.

Versioning

Onze API’s hebben geen versienummer. In plaats daarvan vertrouwen we op het markeren van resources als verouderd (deprecated) 6 maanden voor verwijdering. Bij te verwachten impact door verwijdering van resources zullen we onderzoeken of dit gebruikte connectoren raakt en communicatie overwegen. Nieuwe resources worden toegevoegd zodra ze beschikbaar komen, zonder verdere kennisgeving.