Tutoriels du serveur d'API

Tirer parti des ressources AuverCloud

 Les exemples proposés dans cette page supposent que vous disposiez d'une clé d'application obtenue à partir de votre compte AuverCloud. Si ce n'est pas encore le cas, il n'est pas trop tard pour vous inscrire ou pour vous familiariser avec AuverCloud Studio.

 Les clés d'applications utilisées dans les exemples ci-dessous ne fonctionnent que pour des domaines restreints. N'oubliez pas de les remplacer par les votres quand vous réutilisez le code source.

 Le guide de référence intègre un banc d'essai pour la plupart des ressources. N'hésitez pas à les tester.


Tutoriel 1 : Requête GET avec l'URL du serveur

Le plus simple appel d'API à partir de votre navigateur

Dans lexemple ci-dessous, l'appel à la ressource location se fait grâce aux paramètres intégrés à l'URL.

  • L'adresse est celle du serveur AuverCloud en mode sécurisé : api.auvercloud.com
  • Le paramètre api a comme valeur le nom de la ressource appelée  : location
  • Le paramètre key a pour valeur une clé d'application obtenue à partir d'AuverCloud Studio.
https://api.auvercloud.com/?api=location&key=2de7cf2043693db2ee898479a6e4452955f144f3abbac

La réponse est une chaîne JSON au format AuverCloud par défaut, à savoir composée des 3 éléments suivants :

  • code est le code de retour qui vaut "200" en cas de réponse sans erreur.
  • msg est un message court qui décrit rapidement l'erreur s'il y en a.
  • data est la réponse elle-même. Ici il s'agit également d'une chaîne JSON.
{
    "code":"200",
    "msg":"OK",
    "data":{
                "ip":"xxx.yyy.zzz.ttt",
                "country":"FRANCE"}
}

  Le guide de référence décrit la liste des erreurs communes à l'ensemble des ressources, ainsi que les erreurs spécifiques pour chacune.

  Certaines ressources retournent par défaut d'autres format de réponse (ex. HTML, RSS, PNG), mais il est toujours possible de récupérer la réponse au format JSON.

Tutoriel 2 : Requête en JavaScript

AuverCloud fournit un client JavaScript, cross-domain, compatible avec tous serveurs HTTP

Dans cet exemple, qui accède à la même ressource que dans l'exemple précédent, on charge les librairies nécessaires à l'API JavaScript : jQuery et le runtime client AuverCloud.

La méthode arc.api(parameters, options) est ensuite utilisée pour l'appel de l'API location.

  Le guide de référence décrit les fonctions et options du client AuverCloud.

  Plus d'informations sur la ressource location.


						

Tutoriel 3 : Requêtes multiples en JavaScript

Plus simple avec la méthode d'initialisation du client AuverCloud

Cet exemple se différencie du précédent par la méthode arc.run(key,options) qui assure des fonctions d'initialisation :

  • Définition de la clé par défaut (key).
  • Définition du mode debug (false par défaut) qui affiche des messages dans la console lors des appels d'API, des réponses, voire de la progression.
  • Chargement des contenus AuverCloud (non utilisé dans cet exemple).
  • Exécution de callback à l'issue de l'ensemble de l'initialisation.

On voit ainsi que la syntaxe est allégée par rapport aux exemples précédents puisqu'il n'est plus nécessaire de préciser les paramètres url et key à chaque appel.

Avec ces premiers exemples et le guide de référence, vous voici prêt(e) pour utiliser l'API AuverCloud dans vos propres applications.

Il est temps de voir les possibilités offertes par le client AuverCloud pour la publication de contenus.


						

Tutoriel 4 : Publier des contenus en HTML + JavaScript

Quelques attributs dans une page HTML

Un aperçu live de l'exemple suivant est disponible sur JSFiddle. Pour reproduire cet exemple vous devrez utiliser votre propre clé et vos propres contenus.

Ici le chargement des contenus nécessitent les éléments suivants :

  • Les librairies JavaScript comme dans les exemples précédents.
  • La feuille de style pour les contenus AuverCloud.
  • Les attributs de contenu AuverCloud dans les tags dans les lesquels ils seront intégrés :
    • arc-text pour les contenus de type texte
    • arc-picture pour les contenus de type image ou diaporama
    • arc-text pour les contenus de type menu

  Une hauteur doit être définie pour les contenus arc-picture, faute de quoi une hauteur de 200px sera appliquée.

  Si elle est définie, l'option callback de arc.run() est exécutée après le chargement de tous les contenus de la page.

 content_pub est la ressource de base principale utilisée dans cet exemple et dans celui qui suit à travers les librairies JavaScript et PHP.


						

Tutoriel 5 : Publier des contenus en HTML + PHP

Intégrer des contenus dans un site web indexable

Cette seconde méthode est à privilégier pour des contenus qui doivent être intégrés dans un site web puis indexés par des moteurs de recherche.

En effet, avec l'intégration en JavaScript telle que décrite dans l'exemple précédent, les contenus sont ajoutés après le chargement de la page. Le risque est alors fort que les moteurs de recherche ne les prennent pas en compte.

Le code source suivant est l'équivalent HTML+PHP de l'exemple précédent dont il se distingue par plusieurs points :

  • La librairie client PHP AuverCloud doit être incluse et initialisée avec une clé d'application.
  • La méthode PHP d'accès aux contenus $arc -> content($ctype, cname) assure une fonction équivalente aux attributs de contenus de l'exemple précédent.
  • Les librairies JavaScript deviennent optionnelles pour l'affichage des contenus. Elle ne sont nécessaires que pour les animations des diaporamas.
<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8" />
		<link type="text/css" rel="stylesheet" href= "https://www.auvercloud.com/run/css/arc.3.css" />

		<!-- Include and init AuverCloud content PHP client -->
		<?php
		include 'arc.3.php';
		$arc = new AuverCloud("2de7cf2043693db2ee898479a6e4452955f144f3abbac");
		?>
		<!-- With AuverCloud PHP client the following JavaScript libraries are optional and required only in 2 cases: (1) Slideshow content display (2) AuverCloud API calls -->
		<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
		<script src="https://www.auvercloud.com/run/js/arc.3.js"></script>
	</head>
	<body>
		<div><?php echo $arc -> content("text", "demo_text"); ?></div>
		<hr>
		<div><?php echo $arc -> content("picture", "demo_slide"); ?></div>
		<hr>
		<div><?php echo $arc -> content("menu", "demo_menu"); ?> </div>
	</body>
	<script>
		/* Optional: See comment above.
		 * By default of the AuverCloud JavaScript librairy, slideshows are limited to the static display of their first picture.
		 */
		$(function() {
			arc.run("2de7cf2043693db2ee898479a6e4452955f144f3abbac");
		});
	</script>
</html>

Tutoriel 6 : Blog et flux RSS

Utiliser les fonctions d'archivage d'AuverCloud Studio

Pour terminer, pas de tutoriel à proprement parler, mais quelques mots sur les ressources content_log et content_rss. Effet, ces deux ressources donnent accès aux différentes versions archivées d'un contenu texte (voir CONTENUS > Textes dans AuverCloud Studio.) et permettent de créer des blogs et des flux RSS sans effort.

C'est ainsi que sont définis le blog AuverCloud, l'application de démo associée Mobile blog, et le flux RSS. Pour comprendre comment mettre en place ces contenus, reportez-vous simplement au guide de référence et au code source des exemples cités.

 content_pub permet non seulement de récupérer la version courante d'un contenu texte, mais également une version archivée grâce au paramètre cdate ou udate.