L'API Kontainer facilite l'intégration de vos logiciels existants à la plateforme Kontainer. Cette interface logiciel à logiciel permet à vos applications d'échanger des données avec Kontainer et peut servir à automatiser de nombreux processus.
Nous présentons ci-dessous les bases de la configuration de l'API.
Les informations de cet article sont techniques et s'adressent aux développeurs chargés de la configuration de l'API. Si vous avez des questions, n'hésitez pas à nous contacter.
Rendez-vous sur la page d'intégration de Kontainer pour en savoir plus sur notre API, notamment sur les cas d'usage et les avantages.
Code de l'API
Accédez directement au code de l'intégration de l'API ICI.
À NOTER : vous devez utiliser l'URL propre à votre Kontainer à la place de celle des exemples des liens ci-dessus (« app.kontainer.com »).
Pour commencer
Pour utiliser l'API Kontainer, vous avez besoin d'un compte Kontainer et d'un jeton d'accès à l'API.
Contactez votre administrateur local ou le support Kontainer pour savoir comment obtenir un accès à l'API Kontainer.
Authentification
L'API Kontainer utilise OAuth pour l'authentification. Une fois que vous avez reçu un jeton d'accès à l'API, vous devez le transmettre dans chaque requête, dans l'en-tête Authorization, avec la valeur « Bearer ».
Toutes les requêtes doivent contenir votre jeton d'accès à l'API dans l'en-tête Authorization : Authorization: Bearer {{access-token}}
Négociation de contenu
Toutes les requêtes doivent inclure l'en-tête : Accept: application/vnd.api+json .
Les requêtes qui envoient des données JSON doivent inclure l'en-tête : Content-Type: application/vnd.api+json
Standard JSON:API
L'API Kontainer est une API RESTful qui suit le standard JSON API. Vous pouvez vous référer à ce standard pour en savoir plus sur la structure des documents de requête et de réponse.
Types de ressources
L'API expose les types de ressources suivants : 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 et job logs.
Opérations d'écriture
L'API prend en charge les opérations d'écriture sur l'ensemble des ressources : POST pour créer, PATCH pour modifier et DELETE pour supprimer. Elle n'est pas en lecture seule.
Limites de débit
Les limites de débit standard de l'API s'appliquent à tous les points d'accès que nous proposons, et la limite est de 500 requêtes par minute. Si vous dépassez la limite définie, l'API répond avec le message : 429: Too Many Attempts.
Codes de réponse
L'API Kontainer répond avec des codes d'état HTTP et des codes et messages d'erreur au format JSON.
Codes d'état HTTP
Le tableau suivant donne un aperçu des codes d'état HTTP renvoyés.
| Code d'état HTTP | Texte | Description |
|---|---|---|
| 200 | OK | Succès. |
| 201 | Created | Objet créé. |
| 204 | No Content | Aucun contenu renvoyé. |
| 401 | Unauthorized | Le jeton est manquant ou invalide. |
| 403 | Forbidden | Ressource ou requête non prise en charge. |
| 404 | Not Found | Objet introuvable. |
| 406 | Not Acceptable | Requête non acceptable. |
| 409 | Conflict | Conflit d'état de l'application ou de la ressource. |
| 422 | Validation Error | Erreur de validation. |
| 429 | Too Many Requests | Limite de débit dépassée. |
Messages d'erreur
L'exemple suivant illustre l'aspect d'un message d'erreur pour le code d'état HTTP 401 - Unauthorized.
Filtres
Vous pouvez appliquer des filtres aux points d'accès qui les prennent en charge, pour limiter les résultats renvoyés. Les filtres s'appliquent avec le paramètre de requête filter. Les champs de filtre pris en charge figurent dans la section Filter Attributes de chaque point d'accès.
Exemples :
Obtenir une liste d'éléments ou de produits d'une catégorie :
filter[description][like] : Shoes
Trouver des éléments par EAN exact :
filter[ean][eq] : 4194382028137
Trouver des éléments postérieurs à une date donnée :
filter[released_on][gt] : 2020-01-01
Trouver des éléments dont le coût unitaire est supérieur ou égal à 22,50 et inférieur à 50,00 :
filter[unit_cost][gte] : 22.50
filter[unit_cost][lt] : 50.00
Vérifier si des fichiers sont référencés dans un champ de données PIM :
filter[asset][exists] : 1
filter[asset][exists] : 0
Qualificateurs de filtre
- Égal à : [eq]
- Dans : [in]
- Comme : [like]
- Supérieur à : [gt]
- Supérieur ou égal à : [gte]
- Inférieur à : [lt]
- Inférieur ou égal à : [lte]
- Pas dans : [notin]
- Différent de : [ne] (PIM uniquement)
- Existe : [exists] (PIM uniquement)
À noter : les qualificateurs de filtre autorisés dépendent de l'élément recherché.
Documents composés
JSONAPI – Compound Documents (en anglais)
Pour réduire le nombre de requêtes HTTP, vous pouvez demander que les réponses des points d'accès concernés « incluent » des ressources liées en plus des ressources principales demandées. Les ressources incluses se demandent avec le paramètre de requête include. Les inclusions prises en charge figurent dans la section Available Includes de chaque point d'accès.
Exemples :
- Dans le point d'accès GET /elements, pour inclure les options d'élément associées :
include: element_option - Dans le point d'accès GET /items, pour inclure les éléments racine, parent et enfants :
include: parent_item,root_item,children
Pagination
Les réponses sont paginées, avec une taille de page configurable. Aucun point d'accès en masse ni webhook n'est proposé.
Code de l'API
Accédez directement au code de l'intégration de l'API ICI.
À NOTER : vous devez utiliser l'URL propre à votre Kontainer à la place de celle des exemples des liens ci-dessus (« app.kontainer.com »).