API Front-Office

L'API Publique Front-office, ou API PFO, permet aux développeurs front-end de créer de nouvelles interactions avec leur site par l’utilisation d’une API sous forme de Web service. Le but est d’ouvrir un accès dédié et structuré entre un client web (navigateur) et Kiubi.

Chaque site dispose de son point d’accès permettant aux internautes d’accéder aux données du site stockées sur Kiubi. Ces points d’accès sont publics dans le sens où il n’y a pas de restrictions d’accès si l’API est activée sur le site.

Une fois l’API activée, cliquez sur le lien "Accéder à l'API Sandbox".

Le Sandbox est une vue fonctionnelle et documentée de toutes les fonctions disponibles via l’API PFO du site. Chaque site dispose de son propre Sandbox.Toutes les fonctions sont regroupées thématiquement (blog, cms, catalogue, panier, ...). Chaque fonction est ensuite détaillée : description, URL, arguments attendus, contenu attendu de la réponse, codes erreurs possibles. Un bouton "Tester" permet de créer une requête vers l’API du site et de récupérer toute 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.

Pour un premier test, récupérons la liste des billets du blog. Pour cela, cliquer sur le lien "/blog" qui contient tous les points d’entrée relatifs au blog. Cliquer sur "GET /blog/posts.json" pour utiliser ce point d’entrée.

Cliquez sur le bouton "Tester". Le sandbox va alors exécuter une requête à l’API du site 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. Les billets du blogs sont listés 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

Intéragir avec sa session

L'API partage la même session que le visiteur du site. Il en découle que l'API permet par exemple d'authentifier directement un internaute ou de modifier son panier. Prenons justement le cas de l'ajout d'un produit à votre panier. Pour cela, assurez vous d'utiliser l'API d'un site e-commerce et d'avoir au moins un produit en stock dans votre catalogue. Utilisons l'API pour trouver l'identifiant de la variante de produit qu'on va ajouter au panier.

Pour cela, dépliez le point d'entrée GET /catalog/product.json. Ce point d'entrée permet de lister les produits du catalogue. Afin de rajouter les informations concernant les variantes de ces produits, il faut utiliser le paramètre extra_fields. Cherchez le champ extra_fields dans les paramètres du point d'entrée et cliquez sur le lien variants. Le champ texte se remplit avec la chaine variants.

Cliquez sur "Tester" pour lancer la requête. La liste des produits va s'afficher dans le champ Response Body. Explorer la liste jusqu'à trouver le tableau des variantes d'un produit (attribut variants) et noter la valeur du champ id.

Ouvrez le point d'entrée PUT /cart/items/{variant_id}.json, saisissez l'identifiant de la variante dans le champ variant_id puis cliquez sur "Tester".

La réponse à cette requête contient dans le noeud data.summary un résumé de ce qui s'est passé (ici l'ajout avec succès de la variante au panier). Le noeud data.cart contient toutes les informations du panier (liste des produits, adresse et frais de livraison,...).

Rendez-vous maintenant sur le site et vérifiez que votre panier contient bien ce produit !

Intégration de l'API au site

Nous fournissons un client JavaScript, utilisant le framework jQuery, pour vous connecter à l'API PFO. Les sources et la documentation du client sont disponibles sur GitHub à l'adresse suivante : https://github.com/Kiubi/api-pfo-JS.

Pour les intégrateurs, nous fournissons également une version minifiée et numérotée, directement utilisable, à l'adresse suivante :

https://cdn.kiubi-web.com/js/kiubi.api.pfo.jquery-1.2.min.js

Le plugin requiert à minima la version 1.8.2 de jQuery. Pour intégrer le client à votre site, ajoutez les balises suivantes à vos pages :

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script type="text/javascript" src="{cdn}/js/kiubi.api.pfo.jquery-1.2.min.js"></script>

Exemple d'intégration sur "Bootstrap"

Nous allons maintenant modifier un site en partant du thème graphique "Bootstrap", disponible par défaut sur Kiubi. Ce thème intègre déjà jQuery et le client API javascript de Kiubi. Nous allons ajouter un formulaire d'identification qui utilise l'API et récupérer quelques informations sur le visiteur connecté.

Les fichiers javascripts sont inclus dans la balise <head> de tous les templates à l'aide du fichier :

fr/includes/js-head.html

On y retrouve les balises <script> :

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
...
<script type="text/javascript" src="{cdn}/js/kiubi.api.pfo.jquery-1.2.min.js"></script>

Le formulaire d'identification sera placé dans le widget panier, situé dans l'entête de toutes les pages. On va y ajouter des champs login et mot de passe pour permettre à l'utilisateur de s'identifier sur le site tout en restant sur la même page.

Pour cela, éditez le template du widget panier theme/fr/widgets/commandes/panier/index.html.

<!--
Template du Widget "Panier"
-->

<!-- BEGIN:main -->
<div class="panier">
<!-- BEGIN:nonidentifie -->
<p class="login"><a id="api-link-login" href="/compte/">Se connecter</a>
  <span style="display:none;"> :
   <label for="api-login">Identifiant : </label>
   <input type="text" class="field" id="api-login" size="10"/>
   <label for="api-pwd">Mot de passe : </label>
   <input type="password" class="field" id="api-pwd" size="10"/>
   <input id="api-submit" type="button" class="submit" style="padding:3px;" value="Ok" />
  </span>
</p>

<script type="text/javascript">
  $(function(){
   // Interception du clic sur le lien "Se connecter"
   // et affichage du mini formulaire de connexion
   $(document).on('click', '#api-link-login', function(){
    $('p.login > span').toggle();
    return false;
   });


   // Login sur le click du bouton du mini formulaire
   $(document).on('click', "#api-submit", function(){
    var login = $("#api-login").val();
    var pwd = $("#api-pwd").val();


    // Pas de requête si aucun login ou aucun mot de passe
    if(login == '' || pwd == '') {
     $("p.login input.field").css('border', '2px solid red');
     return;
    }


    // Connexion à kiubi
    var query = kiubi.login(login, pwd);


    // En cas de connexion réussie
    query.done(function(meta, data){
     $(".login").hide().after('<p class="compte"><a href="/compte/">'+data.firstname+' '+data.lastname+'</a> - <a id="api-link-logout" href="/compte/logout.html">D&eacute;connexion</a></p>');


     // Récupération des commandes de l'utilisateur
     kiubi.users.getOrders(data.user_id).done(function(meta, data){
      if(data.length) {
       $('p.compte > a:first').before('Etat de votre dernière commande : '+data[0].status+' - ');
      }
     });
    });


    // En cas de connexion échouée
    query.fail(function(meta, error, data){
     $("p.login input.field").css('border', '2px solid red');
    });    
   });


   // interception du clic sur le lien "Déconnexion"
   $(document).on('click', '#api-link-logout', function(){


    // Déconnexion de l'utilisateur courant
    kiubi.logout().done(function(meta, data){
     $("p.compte").hide();
     $("p.login").show();
     $("p.login span").hide();
     $("p.login input.field").removeAttr('style');
     $("#api-pwd").val('');
    });
    return false;
   });
  });
</script>
<!-- END:nonidentifie -->

<!-- BEGIN:identifie -->
<p class="compte"><a href="/compte/">{prenom} {nom}</a> - <a href="/compte/logout.html">D&eacute;connexion</a></p>
<!-- END:identifie -->

<p class="panier_link"><a href="/ecommerce/panier.html" title="Détail du panier">{nb_produits} article{pluriel_produits} - {total}</a></p>
</div>
<!-- END:main -->

Seuls les internautes non identifiés sur le site voient un lien "Se connecter" dans l'entête car ce lien se trouve dans se trouve dans le bloc nonidentifie. S'ils cliquent dessus, les champs identifiant et mot de passe apparaissent.

Le clic sur le bouton "Ok" va appeler la méthode login du plugin qui va utiliser l'API pour vérifier le couple identifiant et mot de passe et connecter l'internaute. Si l'identification échoue, les champs identifiant et mot de passe sont entourés de rouge.

Si elle réussit, une deuxième requête vers l'API est lancée via la méthode users.getOrders du plugin pour récupérer la liste des dernières commandes de l'internaute. Si l'internaute a au moins une commande, on affiche son état dans l'entête.

Tous les accès se font grâce à HTTP, via le nom de domaine principal du site (ex : https://monsite.kiubi-web.com/api/v1/).

$ curl -i http://monsite.kiubi-web.com/api/v1/blog/posts.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

[]

Encodage de caractères

Le charset supporté par les requêtes est l'UTF-8.

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 "http://monsite.kiubi-web.com/api/v1/blog/posts.json?sort=comments_count"

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 "email=test%40example.org" "http://monsite.kiubi-web.com/api/v1/newsletter.json"

Paramètres courants

Les paramètres suivants sont utilisés très largement dans l'API et ont un fonctionnement homogène.

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.

Le corps des réponses respecte une structure commune. Une réponse simple peut être la suivante :

$ curl -i http://monsite.kiubi-web.com/api/v1/blog/categories.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: [
        {
          "id": 1,
          "title": "Générale",
          "posts_count": 1,
          "slug": "Generale",
          "url": "/blog/Generale/"
        }
    ]
}

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

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 http://monsite.kiubi-web.com /api/v1/blog/posts/9999.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

Codes HTTP

Encodage de caractères

Les caractères non ASCII sont transmis sous leur forme unicode (\uXXXX). Cet encodage est notamment compris nativement par javascript, quel que soit le charset de la page dans laquelle l'API est utilisée.

L'encodage à utiliser pour l'envoi de donnée vers l'API est l'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 :

• date au format YYYY-MM-DD

Toutes les dates horodatées sont retournées aux formats :

• UNIX timestamp
• date au format YYYY-MM-DD HH:MM:SS

Format de retour

L'API supporte le format JSON. Le format de retour est précisé lors 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.

Les points d'entrée privés se basent sur une authentification par Cookie. L'API partage la même session que le visiteur du site. Il en découle que l'API permet d'authentifier directement un internaute, et qu'un internaute connecté au Front-office a accès directement à ses données via l'API :

$ curl -i http://monsite.kiubi-web.com/api/v1/session.json?login=u&password=pwd&method=put


HTTP/1.1 200 OK
Date: Tue, 30 Jul 2013 09:12:01 GMT
Server: Apache
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Last-Modified: Tue, 30 Jul 2013 09:12:01 GMT
Set-Cookie: PHPSESSID=63f95d9d1676bd9987df65a6ba862d13; path=/
Content-Length: 146
Content-Type: application/json


{
"meta": {
   "success":true,
   "status_code":200,
   "link":[],
   "rate_limit": 120,
   "rate_remaining": 120
},
"error":[],
"data":{
   "is_logged":true,
   "user_id":1,
   "firstname":"John",
   "lastname":"Doe",
   "gender":"H"
}
}

Dans un navigateur, le cookie de session est automatiquement envoyé à chaque requête et récupérer dans chaque réponse. Sans navigateur, il est nécessaire de récupérer le contenu de l'entête Set-Cookie des réponses de l'API pour le renvoyer dans les prochaines requêtes.

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.

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 :

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 http://monsite.kiubi-web.com/api/v1/blog/posts.json

HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
Status: 200 OK
Vary: Accept, Authorization, Cookie

$ curl -i http://monsite.kiubi-web.com/api/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 http://monsite.kiubi-web.com/api/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 http://monsite.kiubi-web.com/api/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: "/api/v1/new/endpoint.json"
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate

{
    meta : {
        success : true,
        status_code : 301,
        link : { location : "/api/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.

Le quota d'utilisation de l'API PFO a été fixé pour en permettre une utilisation confortable. Chaque utilisateur a droit à 120 requêtes sur une durée de 2 minutes. A chaque requête, le nombre de requêtes restantes est décrémenté de 1. Au bout de 2 minutes, le quota est restauré à 120.

La quantité de requêtes restantes est indiquée dans chaque réponse dans le noeud meta.rate_remaining. Le point d'entrée /api/v1/rate permet également de récupérer cette valeur sans consommer de quota.

$ curl -i http://monsite.kiubi-web.com/api/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 http://monsite.kiubi-web.com/api/v1/blog/posts.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 /api/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, n'hésitez pas à nous contacter !

Vous trouverez sur GitHub les sources et la documentation de plusieurs exemples concrets d'utilisation de l'API de Kiubi.

Produits géolocalisés

Ce tutoriel explique comment utiliser l'API pour afficher une liste de produits sur une carte Google Maps avec la possibilité d'ajouter ces produits au panier directement à partir de la carte. Voir le tutoriel

Suggestion de produits

Ce tutoriel explique comment utiliser l'API pour suggerer des produits à un internaute à partir des produits associés et de ses dernières commandes. Voir le tutoriel

Bundles de produits

Ce tutoriel explique comment utiliser l'API pour créer des bundles de produits. Voir le tutoriel

Variantes multi-critères

Ce tutoriel qui explique comment utiliser l'API pour créer des variantes multi-critères de produit. Voir le tutoriel

Listing dynamique

Ce tutoriel explique comment utiliser l'API pour créer une navigation dynamique, en chargeant des éléments à la demande. Voir le tutoriel

Contrôle de la médiathèque

Ce tutoriel explique comment utiliser l'API pour créer des carrousels et des slideshow dynamiques. Voir le tutoriel

Shortcode

Ce tutoriel explique comment utiliser des shortcodes sur son site, afin d'afficher toutes sortes d'éléments ou widgets (formulaire dismoi, encart produit, ...). L'objectif étant de faciliter l'intégration d'éléments à l'aide de balises simple appelée "shortcode". Voir le tutoriel

Gestion de devis

Ce tutoriel explique comment utiliser l'API pour créer et remplir dynamiquement un formulaire dismoi. On pourra par exemple créer un formulaire de demande de devis alimenté par les produits du catalogue. Voir le tutoriel