API Developers
API Rest
L'"API Developers Back-office" ou DBO permet aux développeurs d'interfacer la Plateforme avec leurs applications grâce à une API sous forme de Web service.
Cette API leur fournit un accès direct et sécurisé aux données de tous leurs sites. Ils peuvent également créer des applications pour des tiers.
L'accès à l'API se fait via l'url https://api.kiubi.com et nécessite un compte sur la plateforme pour requêter et accéder aux données.
Tous les accès se font grâce à HTTPS, via une adresse unique: https://api.kiubi.com
$ curl -i https://api.kiubi.com/v1/sites.json
HTTP/1.1 200 OK
Date: Tue, 30 Jul 2013 08:25:32 GMT
Server: Apache
Content-Type: application/json
Connection: keep-alive
Status: 200 OK
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
{
…
}
Le Sandbox
Le Sandbox est une vue fonctionnelle et documentée de toutes les fonctions disponibles via l'API DBO de la plateforme. Toutes les fonctions sont regroupées thématiquement. Chacune de ces fonctions est ensuite détaillée : description, URL, arguments attendus, contenu attendu dans la réponse, codes erreur possibles. Un bouton "Tester" permet de créer une requête vers l'API du site et de récupérer toutes les données de la réponse.
Le Sandbox est à la fois la documentation de l'API et aussi un outil de prototypage pour vos développements.
L'accès au Sandbox est public, tous les internautes peuvent consulter la liste des fonctions et leur documentation. Il est disponible à l'adresse : https://api.kiubi.com/console.
Pour tester les requêtes sur vos sites il est nécessaire de s'identifier au préalable. Pour cela, cliquez sur le bouton "Authentification". Vous êtes alors redirigé vers un formulaire d'identification où vous devez indiquer les identifiants et mot de passe de votre utilisateur sur la plateforme. Vous serez redirigé vers le Sandbox en mode connecté et pourrez effectuer des requêtes avec l'API.
Premier test
Pour un premier test, récupérons la liste des sites du compte. Pour cela, cliquez sur le lien "Authentification" en haut du Sandbox et connectez-vous à Kiubi. Vous serez alors redirigé vers le Sandbox en étant connecté.
Cliquez sur la ligne "sites" pour la déplier, puis sur "GET /sites.json" pour utiliser ce point d'entrée.
Cliquez sur le bouton "Tester". Le Sandbox va alors envoyer une requête à l'API et afficher le retour au format JSON dans le champ texte Response Body. Toutes les informations propres à la réponse comme les entêtes HTTP et le code HTTP sont également affichées. Le champ Request URL indique l'adresse de la requête qui a été utilisée. La liste des sites se trouve dans le nœud data de la réponse. Une réponse contient toujours les nœuds suivants :
meta: informations sur la réponse elle mêmeerror: erreurs éventuellesdata: données de la réponse
Client PHP
Nous fournissons un client PHP pour vous connecter à l'API DBO. Les sources et la documentation du client sont disponibles sur GitHub à l'adresse suivante : https://github.com/Kiubi/api-dbo-PHP.
Le client requiert à minima la version 5.2 de PHP avec l'extension cURL.
Génération d'une clé personnelle
La gestion des clés personnelles de l'API DBO se trouve sur la page API de l'Espace prestataire. Chaque utilisateur peut créer, modifier et supprimer ses clés personnelles dans la limite de 10 clés par utilisateur.
Il est conseillé de générer une clé différente pour chaque application utilisée.
Chaque clé personnelle doit rester secrète car elle permet d'accéder à l'ensemble des données accessibles par l'utilisateur.
Exemples d'intégration
Récupération des 10 dernières commandes à traiter :
include 'kiubi_api_dbo_client.php';
$API = new Kiubi_API_DBO_Client('XXXXXXXXXXXXXX');
$response = $API->get('sites/monsite/checkout/orders.json?status=pending&limit=10&extra_fields=price_label');
if($response->hasSucceed()) {
$orders = $response->getData();
}
Mise à jour des informations du compte :
include 'kiubi_api_dbo_client.php';
$API = new Kiubi_API_DBO_Client('XXXXXXXXXXXXXX');
$API->put('account/contact.json?firstname=John&lastname=Doe');
Paramètres
Les méthodes de l'API supportent pour la plupart des paramètres optionnels. Pour les requêtes GET, ces paramètres sont à reporter dans l'URL. Par exemple :
$ curl -i "https://api.kiubi.com/v1/sites.json?term=demo"
Pour les requêtes POST, les paramètres non inclus dans l'URL peuvent être passés dans le corps de la requête. Ils devront
être encodés selon la RFC 1738 et l'entête de la requête devra contenir un Content-Type à application/x-www-form-urlencoded.
Par exemple :
$ curl -i -d "name=Menu%20secondaire" "https://api.kiubi.com/v1/sites/monsite/cms/menus.json"
Paramètres courants
Les paramètres suivants sont utilisés très largement dans l'API et ont un fonctionnement homogène.
| Paramètre | Description | Valeurs |
|---|---|---|
| extra_fields | Ce paramètre permet d'augmenter le périmètre d'une réponse en ajoutant des informations complémentaires. | Liste d'options séparées par des virgules |
| sort | Ordre de tri des résultats de la réponse. Critère de tri. | Pour utiliser le même critère mais décroissant, préfixer avec le caractère "-" |
| limit, page | Paramètres de contrôle de la pagination des réponses | Cf section Pagination |
Paramètres optionnels de compatibilité
Les paramètres suivants sont communs à toutes les méthodes de l'API. Ils permettent d'adapter le fonctionnement de l'API à des clients n'implémentant pas tout le protocole HTTP ou avec des contraintes trop importantes pour le développeur.
| Paramètre | Description | Valeurs |
|---|---|---|
| method | Pour les clients ne supportant pas toutes les méthodes HTTP, il est possible d'utiliser le paramètre method pour simuler l'utilisation d'une méthode. | |
| Une requête GET avec un paramètre method=PUT sera donc considérée par l'API comme une requête PUT. | GET, POST, PUT ou DELETE | |
| callback | Nom du callback pour obtenir une réponse au format json-p. | Chaine de caractères |
| suppress_response_code | Si ce paramètre est à true, l'API désactive l'utilisation sémantique des codes HTTP. Toutes les requêtes renverront en entête un code HTTP 200 OK. Le code HTTP initialement prévu reste néanmoins lisible dans le corps de la réponse. Le bon ou mauvais déroulement d'une requête devra donc être manuellement vérifié dans les messages contenus dans le corps de la requête. Seule une indisponibilité technique de l'API peut tout de même retourner une erreur de type 500. "true" ou "false". | Par défaut à "false" |
| force_response_mime | Si ce paramètre est renseigné, le mime/type par défaut application/json du format de sortie sera substitué par cette valeur. | "text/plain" ou "text/html" |
Réponses
Le corps des réponses respecte une structure commune. Une réponse simple peut être la suivante :
$ curl -i https://api.kiubi.com/v1/sites.json
HTTP/1.1 200 OK
Server: Apache
Date: Tue, 30 Jul 2013 08:25:32 GMT
Content-Type: application/json
Connection: keep-alive
Status: 200 OK
Content-Length: 172
Cache-Control: max-age=0, private, must-revalidate
{
meta: {
success: true,
status_code: 200,
link: [],
rate_limit: 1000,
rate_remaining: 1000
},
error: [],
data: [
{
…
}
]
}
Le corps de la réponse est constitué d'un objet meta qui contient des informations relatives à la requête ainsi qu'un objet data qui contient les données qu'on souhaite récupérer. Son contenu est propre à chaque méthode de l'API.
Description du noeud META
| Paramètre | Description | Toujours présent | Valeur |
|---|---|---|---|
| meta.succes | Renseigne sur le succès ou l'échec de l'appel. A la moindre erreur, le paramètre est à "false". | Oui | "true" ou "false" |
| meta.status_code | Code HTTP de la réponse. Si le paramètre suppress_response_code a été utilisé dans la requête, le développeur trouvera ici le code HTTP initial de la réponse. | Oui | Code HTTP sur 3 chiffres. |
| meta.link | Groupe de lien hypermédia. Explicite les interactions possibles avec la réponse. L'utilisation la plus courante est la pagination des résultats. | Oui (peut être vide) | Liste d'URL |
| meta.rate_limit | Quota maximum de requêtes | Oui | Entier |
| meta.rate_remaining | Nombre de requêtes restantes | Oui | Entier |
En cas d'erreur la propriété meta.succes est à false. La réponse contient alors des paramètres supplémentaires. Un
exemple de réponse avec erreur est :
$ curl -i https://api.kiubi.com /v1/sites/notfound.json
HTTP/1.1 200 OK
Server: Apache
Date: Tue, 30 Jul 2013 08:25:32 GMT
Content-Type: application/json; charset=iso-8859-1
Connection: keep-alive
Status: 200 OK
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
{
meta: {
success: false,
status_code: 404,
link: [],
rate_limit: 120,
rate_remaining: 120
},
error: {
code: 4401,
message: "Le site n'existe pas",
help: ,
fields: []
},
data: null
}
Une réponse d'erreur contient des paramètres d'erreur supplémentaires.
Description du noeud ERROR
| Paramètre | Description | Toujours présent EN CAS d'ERREUR | Valeur |
|---|---|---|---|
| Error.code | Numéro de l'erreur rencontrée | Oui | Entier |
| Error.message | Message d'erreur global. Typiquement une phrase. | Oui | Chaine de caractères |
| Error.help | Lien vers une page de l'aide permettant de résoudre l'erreur | Oui | URL |
| Error.fields | Liste détaillée des erreurs. | Oui | Tableau |
| Error.fields.[n].message | Message d'erreur | Oui | Chaine de caractères |
| Error.fields.[n].field | Paramètre de la requête à l'origine de l'erreur | Oui | Chaine de caractères |
| Error.fields.[n].extra | Eventuelles précisions sur l'erreur | Non | Variable |
Codes HTTP
| Code HTTP | Signification |
|---|---|
| 200 | La requête s'est bien déroulée |
| 301 | Redirection permanente |
| 302 | Redirection temporaire |
| 304 | Ressource non modifiée depuis la dernière requête |
| 400 | La syntaxe de la requête est erronée |
| 403 | Accès refusé |
| 404 | Ressource non trouvée |
| 405 | Méthode HTTP non autorisée |
| 413 | La requête est trop volumineuse |
| 500 | Erreur interne du serveur |
| 503 | Service temporairement indisponible ou en maintenance |
Format et Encodage
La réponse d'une requête api est encodée en UTF-8. En cas d'erreur d'encodage, l'API renvoie une erreur "Caractère non autorisé" et un code HTTP 400.
Format des dates
Le fuseau horaire de l'API est "Europe/Paris". Toutes les dates et heures s'entendent dans ce fuseau aussi bien à la lecture qu'à l'écriture de données.
Toutes les dates sont retournées aux formats suivants :
| Champ | Format | Exemple |
|---|---|---|
| champ | YYYY-MM-DD | 2012-04-23 |
Toutes les dates horodatées sont retournées aux formats :
| Champ | Format | Exemple |
|---|---|---|
| champ | YYYY-MM-DD HH:II:SS | 2012-04-23 12:54:03 |
| champ+'_timestamp' | Timestamp unix | 1335178443 |
Format de retour
L'API supporte le format JSON. Le format de retour est précisé dans l'URL de la requête par l'extension indiquée (.json).
Sans extension, le format de la réponse est par défaut le JSON. Le format de réponse est également reprécisé dans l'entête Content-Type (application/json).
Pour des besoins de rétrocompatibilité, le Content-Type peut être forcé à text/plain ou text/html, à l'aide du paramètre force_response_mime.
Authentification
Un token d'authentification (ou clé personnelle) est obligatoire pour chaque requête sur l'api DBO. Ce token peut être passé en paramètre ou en entête.
En entête :
$ curl https://api.kiubi.com/v1/sites.json?access_token=XXXX
En paramètre :
$ curl https://api.kiubi.com/v1/sites.json -H 'Authorization: token XXXX'
Obtention d'un token
Les tokens des utilisateurs sont gérés dans le backoffice. L'API permet également d'obtenir un token temporaire, valable 24 heures en échange du login et mot de passe d'un utilisateur :
$ curl https://api.kiubi.com/v1/auth/token.json?method=POST&login=...&password=...
{
"meta": {
"success": true,
"status_code": 200,
"rate_limit": 1000,
"rate_remaining": 1000,
"link": []
},
"error": [],
"data": {
"token": "...TOKEN...",
"expiration_date": '2019-02-11 14:21:55',
...
}
}
Le token est retourné dans le champ data.token. Attention toute fois à bien anticiper la date d'expiration de ce token
indiqué dans le champ data.expiration_date.
Hypermédia
Les réponses contiennent un paramètre meta.link qui peut contenir un ensemble de liens contextuels à la ressource. Ces
liens explicitent les URLs vers les ressources directement liés à la ressource courante.
Les développeurs sont vivement encouragés à suivre ces liens plutôt qu'à les reconstruire eux-mêmes. Cela facilite également la prise en compte d'évolutions futures de l'API.
Pagination
Les ressources retournant une liste d'éléments sont paginées. Par défaut, une page est composée de 20 éléments. Le
paramètre limit des requêtes permet de diminuer cette valeur ou de l'augmenter (typiquement jusqu'à 40, mais
certaines requêtes supportent plus). Une valeur supérieure à la limite maximale sera refusée.
Le paramètre page contrôle le numéro de page. Les pages sont numérotées à partir de 0 avec une valeur croissante. La
première page a le numéro 0, la deuxième le 1, etc.
| Paramètre | Description | Valeur |
|---|---|---|
| limit | Nombre d'éléments par page | Entier de 1 à 40. 20 par défaut. |
| page | Numéro de la page | Entier à partir de 0. 0 par défaut. |
Les ressources paginées contiennent des liens de pagination évitant au développeur d'avoir à les construire lui même. Ces liens reprennent tous les paramètres indiqués par la requête initiale :
| Paramètre | Description | Valeur |
|---|---|---|
| meta.link.first_page | Lien vers la première page | URL |
| meta.link.next_page | Lien vers la page suivante | Contient une URL sauf pour la dernière page ou le paramètre est à "false". |
| meta.link.previous_page | Lien vers la page précédente | Contient une URL sauf pour la première page ou le paramètre est à "false" |
| meta.link.last_page | Lien vers la dernière page | URL |
| meta.items_count | Nombre d'éléments total | Entier |
| meta.items_per_page | Nombre d'éléments par page | Entier |
| meta.current_page | Page courante | Entier |
Cache
L'API supporte les mécanismes de cache HTTP. Les réponses sont accompagnées d'entêtes de cache que le développeur
devrait respecter. Les entêtes ETag et Last-Modified peuvent être utilisée indifféremment dans les réponses.
Si une de ces entêtes est présente et que la ressource n'a pas été modifiée depuis le dernier appel, une réponse "304 Not Modified" sera alors retournée en réponse. Les réponses 304 ne sont pas comptabilisées dans le quota d'utilisation de l'API, c'est un très bon moyen d'optimiser sa consommation.
Etag
Une réponse peut contenir une entête Etag qui indique un numéro de série. Pour tout rappel ultérieur d'une même
ressource, il est fortement conseillé au développeur d'inclure dans sa requête une entête If-None-Match contenant le
numéro de série de l'élément.
$ curl -i https://api.kiubi.com/v1/sites.json
HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Status: 200 OK
Vary: Accept, Authorization, Cookie
$ curl -i https://api.kiubi.com/v1/blog/posts.json -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Last-Modified: Thu, 23 Jul 2013 11:25:05 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
Last-Modified
Une réponse peut contenir une entête Last-Modified qui indique une date. Pour tout rappel ultérieur d'une même
ressource, il est fortement conseillé au développeur d'inclure dans sa requête une entête If-Modified-Since contenant
cette date.
$ curl -i https://api.kiubi.com/v1/blog/posts.json
HTTP/1.1 200 OK
Cache-Control: private, max-age=60
Last-Modified: Thu, 23 Jul 2013 11:25:05 GMT
Status: 200 OK
Vary: Accept, Authorization, Cookie
$ curl -i https://api.kiubi.com/v1/blog/posts.json -H "If-Modified-Since: Thu, 23 Jul 2013 11:25:05 GMT"
HTTP/1.1 304 Not Modified
Cache-Control: private, max-age=60
Last-Modified: Thu, 23 Jul 2013 11:25:05 GMT
Status: 304 Not Modified
Vary: Accept, Authorization, Cookie
Redirections
L'API peut utiliser les mécanismes de redirection HTTP (codes HTTP 301 et 302) lorsque cela est nécessaire. Le
développeur devra toujours prévoir l'éventualité de recevoir une redirection en réponse à une de ses requêtes. Dans ce
cas la réponse contient une entête Location qui indique l'URL à laquelle le développeur est invité à renvoyer sa
requête. Un exemple de redirection :
HTTP/1.1 301 REDIRECT PERMANENT
Server: Apache
Date: Tue, 30 Jul 2013 08:25:32 GMT
Content-Type: application/json; charset=iso-8859-1
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
Location: "/v1/new/endpoint.json"
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
{
meta : {
success : true,
status_code : 301,
link : { location : "/v1/new/endpoint.json" },
rate_limit: 120,
rate_remaining: 120
},
data : null
}
Le paramètre meta.link.location reprend la valeur de l'entête Location. Si le paramètre suppress_response_code
est à true dans la requête, le code HTTP est un code 200. Il revient au développeur de tester le statut présent dans
meta.link.status_code et de refaire un appel à l'URL indiquée dans meta.link.location.
Redirection 301 : c'est une redirection permanente. Toutes les requêtes vers la ressource désignée devront s'effectuer sur la nouvelle URL.
Redirection 302 : l'utilisation d'une nouvelle URL est temporairement nécessaire. L'URL d'origine est cependant toujours à utiliser pour adresse la ressource.
Les réponses 301 & 302 ne sont pas comptabilisées dans le quota d'utilisation de l'API.
Quota
Le quota d'utilisation de l'API DBO a été fixé pour en permettre une utilisation confortable. Chaque clé donne droit à 1 000 requêtes sur une durée de 15 minutes. A chaque requête, le nombre de requêtes restantes est décrémenté de 1. Au bout de 15 minutes, le quota est restauré à 1 000.
La quantité de requêtes restantes est indiquée dans chaque réponse dans le noeud meta.rate_remaining. Le point
d'entrée /rate permet également de récupérer cette valeur sans consommer de quota.
$ curl -i https://api.kiubi.com/v1/rate.json
HTTP/1.1 200 OK
Date: Tue, 30 Jul 2013 09:12:01 GMT
Content-Length: 114
Content-Type: application/json
{
meta: {
success:true,
status_code:200,
link:[],
rate_limit: 1000,
rate_remaining: 1000
},
error:[],
data:null
}
En cas de dépassement de quota, l'API renverra une erreur 403 :
$ curl https://api.kiubi.com/v1/sites.json
{
meta: {
success: false,
status_code: 403,
rate_limit: 1000,
rate_remaining: 0,
link: []
},
error: {
code: 4300,
message: "Vous avez épuisé votre quota de requête, attendez quelques minutes pour restaurer votre quota.",
help: ,
fields: []
},
data: null
}
Les requêtes qui ne consomment pas de quota sont celles vers le point d'entrée /v1/rate ou celle générant une
réponse 301, 302 ou 304 (cf. sections Cache et Redirections). L'utilisation du cache est le meilleur moyen de
limiter sa consommation.
Si ces quotas sont insuffisants pour votre site, contactez nous !