H2 - P2019

Développement web

Cours 29 - 2016-03-31

PHP

APIs

Application Programming Interface

Définition général :
Ensemble de classes, méthodes et fonctions d'un service

Définition web :
Interface de communication d'un service web accessible par protocole HTTP

Si vous avez créé un site et que vous souhaitez ouvrir vos données sans avoir à fournir trop d'accès et en gardant le contrôle sur les flux, vous pouvez mettre en place une API

Il en existe de très nombreuses et tous les grands en ont une :

Les petits aussi :

Formats

Les données renvoyées peuvent être dans différents formats

  • JSON
  • XML
  • Images
  • Excel
  • PDF
  • ...

Documentation

  • Chaque API est en général accompagnée d'une documentation
  • Elles ne sont pas toujours au top
  • Explorez intégralement la documentation avant de commencer
  • Si vous développez une API, ne négligez pas la documentation

Limites

  • La majorité des APIs possède des limites. Cela permet d'empêcher les abus et une surcharge du serveur.
  • Renseignez-vous sur ces limites et minimisez le nombre d'appels
  • Une bonne astuce consiste à utiliser du cache

REST

Certaines APIs sont qualifiées de REST (Representational State Transfer)

  • URI
  • HTTP
  • MIME types
  • Liens de transition inter-ressource

URI

Dans une URL, il s'agit du chemin après le domaine : http://mon-api.com/ressource/categorie/3/id/1827

L'URI permet d'identifier la ressource et doit être bien prévue avec une architecture logique et compréhensible

HTTP

Dans le cadre d'une API Rest, le choix du protocole permet de définir l'action désirée.

Nous connaissons deux protocoles GET et POST, Il en existe deux autres principaux, PUT et DELETE

  • GET : Récupérer une ressource
  • POST : Ajouter une ressource
  • PUT : Modifier une ressource
  • DELETE : Supprimer une ressource

MIME Types

Les APIs peuvent renvoyer du JSON, des images, du HTML, des excel, etc.

Lorsque la donnée est renvoyée, elle doit être accompagnée d'un MIME Type permettant d'indiquer clairement le type

Liste des mime types

Liens de transition inter-ressource

Pour être considérée comme REST, l'API doit renvoyer de données en fournissant les URI permettant d'accéder aux données voisines

Si par exemple on récupère une catégorie et que celle-ci renvoie des ressources, les URI de ces ressources doivent être indiquée. Cela permet aux développeur de facilement aller récupérer les ressources après avoir récupérer la catégorie.

Bonus

Moins officiellement, on considère une API comme REST dans ces deux conditions :

  • ID : Chaque ressource est identifiée de façon unique avec un ID
  • Stateless : Une URI doit toujours renvoyer le même résultat (sauf si la donnée a changé). Il ne peut pas y avoir de flux d'actions.

Communiquer avec une API

Nous allons prendre comme exemple l'API de météo OpenWeatherMap

Comme de nombreuses APIs, celle-ci nécessite de s'enregistrer afin d'optenir une API KEY.
Il faudra envoyer cette API KEY avec chaque requête


API KEY : 9e8150c9d6fbf87d678d2cf7f7a2c00a

L'API de OpenWeatherMap est gratuite jusqu'à certaines limites

Communiquer avec une API

Dans le navigateur

Puisque les APIs sont accessibles en HTTP via des URLs, on peut les tester directement depuis n'importe quel navigateur

Tapez l'URL suivante dans votre navigateur


http://api.openweathermap.org/data/2.5/weather?q=Paris&APPID=9e8150c9d6fbf87d678d2cf7f7a2c00a

L'API de OpenWeatherMap renvoie du JSON

Pour formater le JSON dans Chrome, installez le plugin JSONView

En tapant des URL dans votre navigateur, vous ne pouvez envoyer que des requêtes en GET

Pour envoyer des requêtes en POST, DELETE, PUT, etc., installez l'application Chrome Postman

Postman

  • Gestion des paramètres
  • Headers
  • Historique
  • Sauvegarde
  • Organisation
  • Testing
  • ...

Communiquer avec une API

En JS

En JS natif


// Instanciate request
var xhr = new XMLHttpRequest();

// Ready stage change callback
xhr.onreadystatechange = function()
{
    // Is done
    if( xhr.readyState === XMLHttpRequest.DONE )
    {
        // Success
        if(xhr.status === 200)
        {
            var result = JSON.parse( xhr.responseText );
            console.log( 'success' );
            console.log( result );
        }
        else
        {
            console.log( 'error' );
        }
    }
};

// Open request
xhr.open( 'GET', 'http://api.openweathermap.org/data/2.5/weather?q=Paris&APPID=9e8150c9d6fbf87d678d2cf7f7a2c00a', true );

// Send request
xhr.send();

Avec jQuery


$.getJSON(
    'http://api.openweathermap.org/data/2.5/weather?q=Paris&APPID=9e8150c9d6fbf87d678d2cf7f7a2c00a',
    function( data )
    {
        console.log(data);
    }
);

Problèmes :

  • Votre API KEY est visible et n'importe qui pourra la récupérer
  • Ce sont les visiteurs qui vont faire les requêtes directement depuis leur navigateur avec leur connexion
  • Pour 100 utilisateurs différents, la même requête sera exécutée 100 fois

Communiquer avec une API

En PHP

Avec CURL


// Instantiate curl
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'http://api.openweathermap.org/data/2.5/weather?q=Paris&APPID=9e8150c9d6fbf87d678d2cf7f7a2c00a');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($curl);
curl_close($curl);

// Json decode
$result = json_decode($result);

// Show result
echo '
';
print_r($result->weather[0]->description);
echo '
';

Avec file_get_contents


// Get content
$result = file_get_contents('http://api.openweathermap.org/data/2.5/weather?q=Paris&APPID=9e8150c9d6fbf87d678d2cf7f7a2c00a');

// Json decode
$result = json_decode($result);

// Show result
echo '
';
print_r($result->weather[0]->description);
echo '
';

Attention, certains serveurs limitent l'utilisation de file_get_contents à des fichiers locaux

Avantages

  • Possibilité de mettre en cache les requêtes
  • Possibilité de sauvegarder les données dans une BDD
  • Requêtes en général plus rapide
  • Les visiteurs ne voient rien (API KEY)