Une brève histoire des API
Les APIs publiques sont partout et ProgrammableWeb. Le premier annuaire des APIs publiques, indique qu’il existe actuellement bien plus de 10 000 APIs publiques. Ce n’est que la pointe de l’iceberg. Le nombre d’APIs qui sont privées dans la nature ou en d’autres termes non documentées et officiellement indisponibles pour nous est probablement 10x ou 20x fois à cela.
Les APIs publiques sont maintenant considérées comme le mécanisme le plus efficace pour intégrer deux applications. Généralement, les APIs sont hébergées dans une application du côté Serveur et exposées aux clients qui les consomment. Les clients peuvent être d’autres applications du côté serveur, des applications mobiles natives ou même des applications de navigateur (mobiles ou ordinateur de bureau).
À lire aussi
Lorsqu’on parle des APIs publiques, peu de choses leur sont communes :
- Elles sont disponibles via un protocole populaire et bien défini, généralement HTTP.
- Elles utilisent JSON ou XML comme format de données.
Ce qui précède n’est pas absolument contraignant mais la majorité des APIs publiques ont cela en commun.
De plus, il y a eu beaucoup de débats sur SOAP par rapport au REST. Autant dire que le style actuellement prédominant est REST. REST utilise plusieurs verbes HTTP de manière efficace pour effectuer des opérations de base d’opérations CRUD ou en termes plus simples :
- Liste (ou Obtenir) tous les enregistrements
- Obtient un ou plusieurs enregistrements en fonction de certains critères de recherche ou ID(s)
- Crée un enregistrement
- Met à jour un enregistrement
- Supprime un enregistrement
Un point clé sur les services Web est qu’il fournit une grande couche de séparation entre le client et le serveur en termes de technologie utilisée. Les applications client sont complètement indépendantes du langage et ou de l’environnement de programmation que vous utilisez du côté du serveur. HTTP est le langage commun qui lie les deux et, par conséquent, vous pouvez écrire votre implémentation de l’API du côté serveur en Java tout en invoquant la même API HTTP via un client Java, un client iOS ou même un client Web.
Google Cloud Endpoints
Google Cloud Endpoints est une solution de Google pour aider à créer une API publique pour votre application App Engine. Cloud Endpoints fournit également des fonctionnalités pour générer des bibliothèques client pour Android et iOS, facilitant ainsi votre tâche d’intégrer la fonctionnalité de votre application principale dans vos applications mobiles sur Android et iOS.
Le diagramme ci-dessous montre la solution Cloud Endpoints (tirée de la documentation officielle) :
Le point à noter est que vous devez avoir une application App Engine. En outre, la manière dont vous stockez vos données ou récupérez vos données ne concerne entièrement que vous. Vous pouvez choisir de travailler avec le magasin de données pour répondre aux fonctionnalités de votre API ou simplement parler à des services externes pour regrouper et présenter la réponse.
Cet article se concentre davantage sur la mécanique de Cloud Points, le jeu d’outils que Google fournit plutôt que sur les meilleures pratiques en matière d’écriture de vos fonctionnalités d’API ou de backend d’API.
Que couvre cet article ?
Tout au long de cet article, on va voir comment nous pouvons écrire une couche API manuellement à l’aide des API Cloud Endpoint. Par couche API, on va écrire une interface REST qui expose un exemple d’objet entité (Citations célèbres) et fournit des méthodes APIs pour l’ajout, la mise à jour, la suppression et la recherche/extraction de devis.
De plus, nous allons voir comment tester votre API localement et finalement la déployer.
Mais pourquoi écrire l’API manuellement ? On pourrait se demander pourquoi écrire l’API manuellement puisque Cloud Endpoints fournit un mécanisme pour générer la classe API à partir des classes d’entités annotées JDO/JPA existantes. Eh bien, il est important de comprendre cela en détail aussi, car cela pourrait aider beaucoup dans le débogage lorsque vous rencontrez des problèmes.
De quoi avez-vous besoin ?
- Compréhension de base de Java Web Development, qui inclut les servlets, JSP, la structure des fichiers WAR, etc.
- Vous disposez d’un environnement de développement fonctionnel pour Google App Engine. Cela inclut le plugin Google Eclipse.
L’environnement du développement nécessaire :
- Eclipse Juno
- Plug-in Google Eclipse avec App Engine SDK 1.8.7
- Machine Mac (mais Windows pourra le faire aussi!)
Attention-> Cloud Endpoints devient GA (General Availability) dans la version 1.8.7 du SDK App Engine. La dernière version d’App Engine au moment de la création cet article est 1.8.8.
Remarque : Il s’agit d’un projet Eclipse que vous pouvez importer directement. Pour réduire la taille du code, il faut supprimer les fichiers JAR du SDK App Engine du dossier WEB-INF \ lib. Ainsi, en fonction de la version de votre SDK App Engine dans l’environnement de développement Eclipse sur votre ordinateur, veuillez créer un lien vers le SDK App Engine approprié pour que le projet se réalise correctement.
Si vous réussissez à importer le projet dans votre configuration Eclipse, le répertoire du projet doit ressembler à ceci :
Citations célèbres (Famous Quotes)
Notre objectif sera d’écrire une API publique qui nous permettra de gérer les Citations Célèbres. Il faut choisir un devis pour le rendre facile à suivre pour tous. Une citation est une déclaration célèbre/philosophique dite par une personne éminente.
Par exemple :
“Soyez le changement que vous voulez voir dans le monde.” – M.K.Gandhi
Nous garderons notre objet Citation simple. Il contiendra les 3 attributs suivants :
- id : Un identifiant unique pour la citation dans notre système.
- auteur : La personne à qui cette citation est attribuée.
- message : Le texte de la citation
Entité de citation
Laissons de côté l’activité API pour le moment. On va d’abord modéliser le devis en tant que classe Java. La classe est présente dans le package com.mindstorm.famousquotes.entity et contient également des méthodes supplémentaires pour equals/hashcode, etc. Le code source Quote.java est illustré ci-dessous :
[gist]8315482[/gist]
Service de citation
Cette section n’est pas requise en tant que telle, mais elle est nécessaire pour définir à la fois l’interface et les détails d’implémentation des différentes méthodes pour gérer Citation (Quote). Supposons donc que vous n’écriviez pas un service Web ou une API publique et que vous deviez créer une classe Service ou une classe Utilitaire pour gérer différentes opérations comme ajouter, modifier, supprimer et lister des Citations, alors la classe pourrait ressembler à ceci.
La classe est présente dans le package com.mindstorm.famousquotes.service et le nom de fichier est QuoteService.java. Le code est montré ci-dessous :
[gist]8315485[/gist]
Parlons un peu de choses importantes ici :
- La classe QuoteService contient des méthodes pour ajouter, mettre à jour, supprimer, obtenir, rechercher et ainsi de suite.
- La mise en œuvre de ces méthodes a été simple et vous devriez être capable de comprendre ce qui se passe.
- Portez une attention particulière à la signature de chacune des méthodes, car Google Cloud Endpoints recherche des signatures spécifiques pour aider à mapper les différentes opérations aux méthodes HTTP telles que GET, PUT, POST et DELETE.
- La méthode ‘add’ contient généralement les différents champs d’attributs en tant que paramètre et renvoie l’objet Citation (Quote) ajouté avec succès à la liste.
- La méthode ‘update’ a l’objet Citation qui doit être mis à jour, en tant que paramètre de la méthode. Cela signifie que l’attribut id, auteur et message doit être renseigné correctement dans l’objet Citation (Quote) transmis en tant que paramètre. Cette méthode renvoie également l’objet Citation qui a été mis à jour.
- La méthode ‘remove’ prend un Identifiant comme paramètre pour la Citation qui doit être supprimé et n’a aucun type de retour.
- Les méthodes ‘get*’ sont utilisées pour récupérer une ou plusieurs Citations correspondantes aux critères requis. Notez que le type de retour est une Liste de Citations.
- Notez également que nous lançons l’objet java.lang.Exception normal, en cas de problème.
Espérons que cela clarifie la façon dont nous aurions écrit une classe Java standard pour aider à travailler avec l’entité Citation et gérer la collection Citation.
Conversion à une classe Google Cloud Endpoint
Maintenant, réfléchissons un instant à ce que nous devrions faire pour exposer le service ci-dessus comme une API REST.
À un niveau élevé, nous devrons faire ce qui suit :
- Identifiez comment nous allons mapper les différentes méthodes aux verbes HTTP équivalents. Dans l’ordre, selon les meilleures pratiques dans les API REST, nous aurons besoin d’exposer les méthodes ‘get*’ sur GET, la méthode ‘update’ sur PUT, la méthode ‘add’ sur POST et la méthode ‘delete’ sur les verbes DELETE. Ça a l’air bien ?
- En outre, nous devons également nous assurer que nous renvoyons les codes de réponse HTTP corrects. Vous auriez entendu parler de HTTP 200 pour OK, HTTP 404 pour Not Found, etc. Alors, par exemple, si nous essayons de mettre à jour une Citation pour laquelle l’ID de Citation n’est pas trouvé, nous devons nous assurer que nous renvoyons le code d’erreur HTTP correct, disons 404 NOT FOUND. Vous trouverez des APIs publiques qui ne sont pas strictement respectées, mais c’est une bonne pratique.
- Une fois que tout cela est en place, nous devons déterminer comment tester cette API.
Compte tenu des points ci-dessus, voyons d’abord comment convertir le fichier QuoteService.java existant en une classe Cloud Endpoints qui aidera à exposer l’API REST. Vous constaterez qu’il s’agit d’utiliser les annotations correctes, les classes Exception des bibliothèques Cloud Endpoints et certaines magies que les Endpoints font derrière la scène en fonction de vos signatures de méthodes.
Regardons la classe convertie avec les API Annotations. La classe Java est présente dans le package com.mindstorm.famousquotes.service et le fichier est QuoteServiceAPI.java. Le code source est indiqué ci-dessous :
[gist]8315491[/gist]
Parlons des quelques points importants :
- Nous avons remplacé la classe java.lang.Exception par la classe NotFoundException qui fait partie des classes Cloud Endpoints. La classe NotFoundException lancera le code de réponse 404 correct et les détails, comme nous le verrons. Regardez l’ensemble des classes Exception exposées par Cloud Endpoints : Exceptions et HTTP.
- Pour identifier cette classe en tant que classe API, nous avons utilisé l’annotation @Api en haut de la classe comme indiqué ci-dessous : @Api(nom=”quoteapi”, version=”v1″, description=”Une API pour gérer des citations célèbres”)
- Nous fournissons un nom à notre API, une version et aussi une description. Si vous ne les fournissez pas, les valeurs par défaut seront prises mais nous les spécifierons ici. En fait, c’est tout ce que nous devons faire puisque Cloud Endpoints peut alors prendre toutes les méthodes publiques de la classe, tisser sa magie basée sur les signatures de méthodes et exposer les méthodes sur les verbes HTTP respectivement. Mais nous serons plus précis comme expliqué ci-dessous.
- Chaque méthode, nous annotons avec @APIMethod dans lequel nous fournissons un nom à la méthode API. Chaque paramètre de méthode que nous voulons que la méthode API considère, nous utilisons l’annotation @Named dans laquelle nous spécifions le nom du paramètre qui sera réellement utilisé par le client lors de la transmission de la valeur. Nous gardons les choses simples pour l’instant, mais si vous êtes intéressé par toute la gamme des annotations, jetez un œil sur Annoter votre API.
- Notez que nous n’avons pas spécifié quelle méthode HTTP (GET, POST, PUT, DELETE) est mappée à quelle méthode Java. Il s’avère que Cloud Endpoints fait du travail intelligent dans les coulisses où il utilisera les bonnes méthodes HTTP. Il semble faire cela en fonction de quels mots clés une méthode commence, la signature de la méthode, etc. Pour conclure, il le fait sur la signature de la méthode, mais conceptuellement vous devriez suivre les règles générales données ci-dessous (tiré de leur documentation). Vous devriez idéalement suivre cette meilleure pratique pour commencer vos noms de méthodes avec les mots clés énumérés ci-dessous, cela rendra les choses plus faciles à comprendre pour tout le monde.
- Notez que si nous voulons, nous pouvons toujours spécifier la méthode HTTP à utiliser via l’annotation @APIMethod. L’attribut httpMethod peut être utilisé pour spécifier GET, POST, etc.
Nous avons terminé avec notre API ! C’était simple … n’est-ce pas ? Oui, mais comment tester l’API et voir les requêtes/réponses HTTP brutes qui vont et viennent ?
Tester votre API localement
Maintenant, vient la partie amusante et indique la quantité de travail que les Développeurs Google ont mis pour le rendre facile pour vous.
Suivez ces étapes :
- Assurez-vous que votre Projet est prêt, compile bien sans erreurs. Exécutez votre Application.
- En supposant que votre Application Web démarre sur le port 8888, visitez l’URL suivant : https://localhost:8888/_ah/api/explorer
Assurez-vous que vous êtes connecté à Internet. Si tout va bien, vous verrez un API Explorer comme indiqué ci-dessous :
Comment cette chose a-t-elle été exposée au-delà du point de terminaison _ah/api ? Eh bien, visitez votre web.xml et vous trouverez une entrée créée pour vous, qui derrière ces scènes invoquera la logique de l’API pour vous.
Vous remarquerez que l’explorateur a utilisé notre @API (nom, version et description) comme nous l’avons indiqué.
Bien, maintenant cliquons sur le lien quoteapi, cela fera apparaître une liste de toutes nos méthodes d’API. Notez que les noms de méthodes ont été pris comme ceux que nous avons fournis dans l’annotation @APIMethod.
Maintenant, ajoutons une citation. Nous allons cliquer sur le lien quoteapi.add. Cela fera apparaître un formulaire où nous pouvons fournir l’identifiant, l’auteur et le message pour la Citation comme indiqué ci-dessous :
En cliquant sur le bouton Exécuter, vous passerez l’appel et ce qui est intéressant à noter, c’est qu’un appel HTTP POST est effectué derrière les scènes. Jetez également un coup d’œil à la réponse HTTP, où le type d’objet de retour, c’est à dire Citation, est correctement rangé dans un objet JSON.
Revenez à la liste et cliquez sur la méthode quoteapi.list. Cela appellera un GET comme indiqué ci-dessous et retourner la collection en tant que réponse JSON.
Maintenant, regardons la méthode quoteapi.getQuote où nous devons fournir le champ ‘id’ pour récupérer l’enregistrement. L’explorateur d’API affiche le formulaire comme indiqué ci-dessous. Nous fournissons l’identifiant comme 1 (pour notre seule citation jusqu’à présent) et il tire un GET et récupère les données.
Portez l’attention sur tout le format GET aussi pour mieux comprendre le format. Vous remarquerez que le format est _ah/api/<APIName>/<APIVersion>/<Objet>/<ID>
Maintenant, regardez ce qui se passe si nous fournissons un identifiant qui n’existe pas.
Comme un enregistrement Citation (Quote) avec id = 2 n’existe pas, il déclenche une exception NotFoundException qui, derrière les scènes, est convertie en la bonne Réponse HTTP 404.
Si nous invoquons la méthode quoteapi.update, cela ouvrira un formulaire dans lequel nous pourrons construire l’objet Citation que nous voulons modifier. Nous fournirons le même ID mais des valeurs différentes pour le message comme indiqué ci-dessous :
En l’exécutant, nous verrons qu’il a déclenché une commande HTTP PUT maintenant :
Si nous récupérons la liste des citations, nous trouverons les données mises à jour :
Enfin, regardons la méthode quoteapi.remove présentée ci-dessous (dans les données d’exemple suivantes, on a ajouté un second enregistrement aussi, donc on supprime ici avec id = 2). Notez qu’il a déclenché une commande DELETE HTTP et comme nous n’avons renvoyé aucun type, il a renvoyé un 204.
De même, si nous essayons de supprimer un enregistrement inexistant, c’est-à-dire id = 3, nous obtiendrons les réponses correctes 404 comme indiqué ci-dessous :
Prochaines étapes
Cela nous amène à la fin de cet article. Dans cet article, nous avons vu combien il était simple d’utiliser la bibliothèque Google Cloud Endpoints pour exposer une API publique. Vous pouvez aller de l’avant et déployer la même chose sur une instance en direct, les choses devraient fonctionner de manière transparente.
