Documentation de l'API Streamfizz
La plateforme Streamfizz fournis aux développeurs une API d'échange de données permettant de consulter le contenu de la plateforme à distance depuis une adresse web.
Grâce à cette API, les applications sont nombreuses et les possibilités d'intégration décuplées !
Définition
L'API Streamfiiz repose sur une architecure REST (Representational state transfer), modèle applicatif original du Web.
Il repose sur un modèle de ressources identifiées de manière unique par une URI et accédées par un jeu limité de méthodes: GET, POST, PUT, DELETE,...
Un Web Service basé sur l'architecture REST se distingue donc des Web services SOAP ou XML-RPC par une approche orientée ressource par opposition à une approche orientée API objet. Il respecte ainsi parfaitement l'esprit original du Web et est beaucoup plus simple d'approche. Il permet en effet de baser les interactions machine-machine sur le même modèle que les interactions homme-machine.
Dans le modèle REST, chaque ressource de l'application est donc identifiée par une URI unique.
On joue ensuite sur la méthode HTTP pour déterminer le type d'action. Le modèle REST définit les actions suivantes:
| Méthode HTTP | Action |
|---|---|
| GET | Lit une ressource |
| POST | Insère une ressource |
| PUT | Met à jour une ressource |
| DELETE | Supprime une ressource |
Bénéfices
Les bénéfices d'une approche REST par rapport à une approche SOAP ou XML-RPC sont les suivants:
- Légèreté (facteur 6 sur les performances selon Amazon qui propose les deux types de services)
- Facilité d'implémentation
- Interopérabilité optimale
- Formats manipulables « à la main »
- Parcourt des ressources via une simple URL (donc directement visibles dans un navigateur)
- Facilité de maintenance
Accès
L'API Streamfizz est disponible à l'adresse suivante :
http://gmfh.webcastor-hd.fr/index.php/api/[RESSOURCE]
La consultation des données s'effectue au travers d'une URL dont la structure indique l'information que vous demandez :
Ex : http://gmfh.webcastor-hd.fr/index.php/api/media/cat_id/6/format/xml
Structure : http://[domaine_plateforme]/index.php/api/[ressource]/[parametres]/format/[format_de_sortie]
Ressources disponibles
5 types de ressources sont actuellement disponibles à la consultation :
| Ressources disponibles | |
|---|---|
| image | Liste les images du système |
| son | Liste les sons du système |
| vidéo | Liste les vidéo du système |
| cat | Liste les vidéo du système |
| media | Liste tous les médias du système |
Ainsi, pour demander la liste des "images" disponibles sur la plateforme pour votre compte utilisateur, l'adresse à contacter sera :
http://gmfh.webcastor-hd.fr/index.php/api/image
Paramètres
Ci-dessous, la liste des paramètres disponibles pour chaque ressources. Ces paramètre peuvent être utilisés pour filtrer vos résultats. Les paramètres sont à indiquer dans l'URL, à la suite de la ressource demandée sous la forme :
clé/valeur/clé/valeur/...
A completer
Formats de sortie
Le webservice Streamfizz vous autorise à recevoir le contenu généré dans divers langages lui permettant de s'adapter à vos méthodes et vos langages de programmation.
Formats de sortie disponibles :
| langage | Explications | Syntaxe d'appel |
|---|---|---|
| XML | Format de sortie par défaut. Le webservice renvoi les résultats sous la forme d'un document XML qui faut ensuite parser. | format/xml |
| JSON | Format de sortie pour réutilisation des données en JAVASCRIPT | format/json |
| SERIALISE | Les données trouvées sont renvoyées sous la forme d'une chaine de caractères contenant les objets sérialisés. Utilisez la fonction unserialize() de php pour retrouver les valeurs sous la forme d'un tableau. | format/serialize |
| PHP | Les données sont retournées sous la forme d'une chaine de caractères contenant une représentation du code PHP généré. Utiliser la fonction eval() de php pour retrouver les valeurs sous la forme d'un tableau. Cette utilisation n'est pas recommandée. | format/php |
| HTML | Simple sortie des données sous la forme d'un tableau HTML. | format/html |
| CSV | Sortie des données sous la forme d'un fichier CSV dont les champs sont séparés par des points-virgules. | format/csv |
Notez que si le format de sortie n'est pas spécifié dans l'URL, le format de retour utilisé sera XML. Enfin, le type de format choisi devra être indiqué en fin d'URL après les paramètres de filtre.
Exemple d'utilisation :
http://gmfh.webcastor-hd.fr/index.php/api/cat/parent_id/2/format/html
Listera toute les catégories dont la catégorie parente possède l'ID 2. Le format de sortie sera HTML.
Exemple d'intégration du WebService
Les web services sont sécurisés par un mécanisme de login / mot de passe correspondant à une authentification basique HTTP. Ainsi, afin de récupérer une réponse du webservice, vous devrez mettre en place un mécanisme d'authentification dans les scripts chargés d'interroger ce dernier.
Récupération des données
Ci-dessous, une des méhodes possible pour lancer une requête au WebService Streamfizz :
<?php /* INFORMATION D'IDENTIFICATION STREAMFIZZ */ $username = 'votre login'; $password = 'votre mot de passe';
/* RECUPERATION DU FICHIER XML */ $curl_handle = curl_init(); curl_setopt($curl_handle, CURLOPT_URL, 'http://gmfh.webcastor-hd.fr/index.php/api/media/cat_id/1/format/xml'); curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl_handle, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl_handle, CURLOPT_USERPWD, $username . ':' . $password);
$output = curl_exec($curl_handle);
curl_close($curl_handle);
echo var_dump($output);
?>
Parcourir le XML
Ci-dessous, une proposition de code vous permettant de parcourir les données XML reçues et les transformer en un tableau associatif; plus facilement utilisable en php :
$xml = new XMLReader(); $xml->xml($output); $assoc = xml2assoc($xml); $xml->close(); echo '<pre>'; print_r($assoc); echo '</pre>'; /* FONCTIONS DE TRANSFORMATION DU FICHIER XML EN OBJET PHP */
function xml2assoc($xml) { $assoc = null; while($xml->read()){ switch ($xml->nodeType) { case XMLReader::END_ELEMENT: return $assoc; case XMLReader::ELEMENT: $assoc[$xml->name][] = array('value' => $xml->isEmptyElement ? '' : xml2assoc($xml)); if($xml->hasAttributes){ $el =& $assoc[$xml->name][count($assoc[$xml->name]) - 1]; while($xml->moveToNextAttribute()) $el['attributes'][$xml->name] = $xml->value; } break; case XMLReader::TEXT: case XMLReader::CDATA: $assoc .= $xml->value; } } return $assoc; }