Met de Kontainer-API integreert je je bestaande software eenvoudig in het Kontainer-platform. Via deze koppeling tussen softwaresystemen kunnen je toepassingen gegevens met Kontainer uitwisselen en kun je veel verschillende processen automatiseren.
Hierna lopen we de basis van de API-inrichting door.
De informatie in dit artikel is technisch en gericht op ontwikkelaars die verantwoordelijk zijn voor de API-inrichting. Heb je vragen? Laat het ons gerust weten.
Bezoek de integratiepagina van Kontainer voor meer informatie over onze API, met onder meer toepassingen en voordelen.
API-code
Ga direct naar de code voor de API-integratie HIER.
LET OP: je moet je eigen unieke Kontainer-URL gebruiken in plaats van die in het voorbeeld in bovenstaande links ("app.kontainer.com").
Aan de slag
Om de Kontainer-API te gebruiken, heb je een account bij Kontainer nodig en een API-toegangstoken.
Neem contact op met je lokale beheerder of Kontainer Support voor meer informatie over hoe je toegang tot de Kontainer-API krijgt.
Authenticatie
De Kontainer-API gebruikt OAuth voor authenticatie. Zodra je een API-toegangstoken hebt gekregen, moet je dit token bij elk verzoek meesturen via de Authorization-header als "Bearer"-waarde.
Alle verzoeken moeten je API-toegangstoken in de Authorization-header bevatten: Authorization: Bearer {{access-token}}
Contentonderhandeling
Alle verzoeken moeten de volgende header bevatten: Accept: application/vnd.api+json.
Verzoeken die JSON-gegevens versturen moeten de volgende header bevatten: Content-Type: application/vnd.api+json
JSON:API-standaard
De Kontainer-API is een RESTful-API die de JSON:API-standaard volgt. Raadpleeg deze standaard voor meer informatie over hoe de verzoek- en antwoorddocumenten zijn opgebouwd.
Resourcetypen
De API biedt de volgende resourcetypen: files, folders, users, tags, channels, elements, element-options, categories, custom-fields, download-templates, video-download-templates, cdn, user-groups, folder permissions, consent wards, consent agreements, consent parties, statistics en job logs.
Schrijfbewerkingen
De API ondersteunt schrijfbewerkingen voor alle resources: POST om aan te maken, PATCH om bij te werken en DELETE om te verwijderen. De API is dus niet alleen-lezen.
Limieten voor aanvragen
De standaardlimieten voor de API gelden voor alle endpoints die wij aanbieden, en de limiet is 500 verzoeken per minuut. Wordt de gedefinieerde limiet overschreden, dan antwoordt de API met de melding: 429: Too Many Attempts.
Antwoordcodes
De Kontainer-API antwoordt met HTTP-statuscodes en op JSON gebaseerde foutcodes en -meldingen.
HTTP-statuscodes
De volgende tabel geeft een overzicht van de HTTP-statuscodes die worden geretourneerd.
| HTTP-statuscode | Tekst | Beschrijving |
|---|---|---|
| 200 | OK | Gelukt. |
| 201 | Created | Object aangemaakt. |
| 204 | No Content | Geen inhoud geretourneerd. |
| 401 | Unauthorized | Token ontbreekt of is ongeldig. |
| 403 | Forbidden | Resource of verzoek wordt niet ondersteund |
| 404 | Not Found | Object niet gevonden. |
| 406 | Not Acceptable | Verzoek niet acceptabel |
| 409 | Conflict | Conflict in de toestand van de toepassing of resource. |
| 422 | Validation Error | Er is een validatiefout opgetreden. |
| 429 | Too Many Requests | Limiet voor aanvragen overschreden. |
Foutmeldingen
Het volgende voorbeeld laat zien hoe een foutmelding eruitziet bij HTTP-statuscode 401 - Unauthorized.
Filters
Op ondersteunde endpoints kun je filters toepassen om de geretourneerde resultaten te beperken. Filters past je toe met de queryparameter filter. De ondersteunde filtervelden vindt je in het onderdeel Filter Attributes van elk endpoint.
Voorbeelden:
Een lijst met categorie-items/producten ophalen:
filter[description][like] : Shoes
Items zoeken op exact EAN-nummer:
filter[ean][eq] : 4194382028137
Items zoeken na een bepaalde datum:
filter[released_on][gt] : 2020-01-01
Items zoeken met een eenheidsprijs groter dan of gelijk aan 22,50 en kleiner dan 50,00:
filter[unit_cost][gte] : 22.50
filter[unit_cost][lt] : 50.00
Controleren of bestanden in een PIM-gegevensveld worden gebruikt:
filter[asset][exists] : 1
filter[asset][exists] : 0
Filtervoorwaarden
- Gelijk aan: [eq]
- In: [in]
- Lijkt op: [like]
- Groter dan: [gt]
- Groter dan of gelijk aan: [gte]
- Kleiner dan: [lt]
- Kleiner dan of gelijk aan: [lte]
- Niet in: [notin]
- Niet gelijk aan: [ne] (let op: alleen PIM)
- Bestaat: [exists] (let op: alleen PIM)
Let op: de toegestane filtervoorwaarden zijn afhankelijk van het element waarop wordt gezocht.
Samengestelde documenten
Om het aantal HTTP-verzoeken te beperken, kun je bij ondersteunde endpoints vragen om bijbehorende resources samen met de gevraagde primaire resources "in te sluiten". Ingesloten resources vraagt je aan met de queryparameter include. De ondersteunde includes vindt je in het onderdeel Available Includes van elk endpoint.
Voorbeelden:
- Bij het endpoint GET /elements om de bijbehorende elementopties in te sluiten:
include: element_option - Bij het endpoint GET /items om de root-, bovenliggende en onderliggende items in te sluiten:
include: parent_item,root_item,children
Paginering
Antwoorden worden gepagineerd met een configureerbaar paginaformaat. Er zijn geen bulk-endpoints of webhooks beschikbaar.
API-code
Ga direct naar de code voor de API-integratie HIER.
LET OP: je moet je eigen unieke Kontainer-URL gebruiken in plaats van die in het voorbeeld in bovenstaande links ("app.kontainer.com").