Guide du développeur

Utilisez les APIs de Kiubi pour ajouter de nouvelles applications à la plateforme

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.
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.
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ême
  • error : erreurs éventuelles
  • data : données de la réponse


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/Trolldidees/kiubi-apiDBO-clientPHP

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');
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 charset supporté par les requêtes est l'UTF-8. En cas d'erreur d'encodage, l'API renvoie une erreur "Caractère non autorisé" et un code HTTP 400.

Utilisation des 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"

Schéma

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 billet 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

Encodage de caractères

La réponse d'une requête api est encodée en UTF-8.

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
champ+'_f' DD/MM/YYYY 23/04/2012


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+'_f' DD/MM/YYYY HHhII 23/04/2012 12h54
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.

Token d'authentification

Le token d'authentification (ou clé personnelle) est obligatoire pour chaque requête sur l'api DBO. Ce paramètre peut être passé sous deux formes :

  • En paramètre de requête : ?access_token=XXXX
  • En entête http : Authorization: token XXXX

Généralités

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
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
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.

Limite

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.

Consultation par API

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 /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 !

Testez Kiubi gratuitement 30 jours pour créer votre site Internet ou votre boutique en ligne

Vous avez une question ? Besoin d'un conseil ou d'un devis ? Contactez-nous !