09/12/2017 TP5 - TP eServices

TP5 - API Management avec Atom et

Anypoint

Télécharger PDF

[../[Link]]

Objectifs du TP
1. Génération d’API avec Atom et le langage RAML

2. Gestion des APIs avec Anypoint Studio et le API Gateway de Mulesoft

Outils et Versions

[Link] 1/21
09/12/2017 TP5 - TP eServices

Atom [[Link] Version: 1.22.1

API Workbench [[Link] Plugin Atom. Version: 0.8.47

Anypoint Studio [[Link] Version: 6.4.1

MySQL [[Link] Version 5.7.20 (ou tout

autre SGBD de votre choix)

Génération d'API avec RAML

RAML

RAML [[Link] (RESTful API Modeling Language) est un langage

pour la dé nition d’API HTTP qui satisfont les exigences de l'architecture REST.
La spéci cation RAML est une application de la spéci cation YAML, qui fournit
des mécanismes pour la dé nition d’APIs RESTful.

RAML est développé et supporté par un groupe de leaders en nouvelles

technologie, provenant de plusieurs entreprises éminentes (Mulesoft, Airware,
Akana, VMware, CISCO…). Leur but est de construire une spéci cation ouverte,
simple et succincte pour la description d’APIs. Ce groupe de travail contribue à la
fois à la spéci cation RAML, ainsi qu’à un écosystème croissant d’outils autours
de ce langage.

API Workbench

Pour écrire un document RAML de manière simple et intuitive, un outil de travail

est fourni, sous la forme d’un plugin pour Atom [[Link] l'éditeur de
texte open source, appelé API Workbench [[Link]

Pour l’installer:

Télécharger et installer Atom: [Link] [[Link]

Dans le menu Préférences, choisir l’option Packages, et taper dans la barre

de recherche: api-workbench.

Une fois le package installé, on devrait trouver dans le menu Packages, un

nouvel élément API Workbench.

[Link] 2/21
09/12/2017 TP5 - TP eServices

Création d’un document RAML

Dans ce qui suit, nous vous indiquons les étapes nécessaires pour créer un
simple chier RAML décrivant une API REST répondant aux recommandations
décrites dans le cours.

Création d’une API RAML

Pour créer un nouveau projet RAML, aller vers Packages -> API Workbench ->
Create RAML Project . Indiquer :

Le répertoire de travail

Le titre de l’API : Par exemple Pet Shop

La version : v1

L’URI de base l’API : /petshop

Cocher uniquement Use RAML 1.0

Le projet obtenu aura l’allure suivante:

Ajout de Ressources et Méthodes

Sous l’onglet Palette de la rubrique Détails, cliquer sur Add new ressource
pour ajouter une nouvelle ressource.

[Link] 3/21
09/12/2017 TP5 - TP eServices

Appeler la ressource /pets

Sélectionner les méthodes get et post

La ressource est désormais créée avec deux méthodes vides.

Remplir les corps et réponses des méthodes

Mettre le focus sur la méthode get:

Dans la Palette, cliquer sur Create new response

Garder le code 200 pour la réponse et cliquer sur OK

Une fois le code de la réponse généré, mettre le focus sur 200:

Cliquer sur Create new Response Body, puis dans la fenêtre qui apparait
cliquer sur OK, pour générer une réponse de type par défaut application/json

Pour la méthode post, générer directement un corps, en cliquant sur Create

new body.

Le résultat apparaît comme suit:

Ajouter des sous-ressources

[Link] 4/21
09/12/2017 TP5 - TP eServices

Pour dé nir le reste des méthodes (put et delete), destinées à agir sur un
élément unique de la ressource pets, et les associer à une sous-ressource:

Mettre le focus sur /pets

Cliquer sur Add new resource

Taper /{id} comme ressource URL, et sélectionner les méthodes put et

delete.

Ajouter un body à put de type application/json

Ajouter une réponse à delete de type 204

Dé nir des types

Pour dé nir le contenu des messages JSON manipulés, dé nir un type comme
suit:

Dans une nouvelle ligne au dessus de /pets, taper ty, puis cliquer sur entrée

Appeler le type Pet, puis dé nir les propriétés name, kind et price, comme
suit:

types: 
Pet:
properties:
name: string
kind: string
price: number

Dé nir Pet comme type pour le corps de la méthode post, en écrivant: type:
Pet au dessous de application/json de la méthode post

Ajouter de même Pet comme type pour la méthode put, et Pet[] pour la
méthode get.

Extraction d’un type de ressources

Pour générer un type de ressources à partir d’une ressource existante:

Mettre le focus sur la ressource /pets

Cliquer sur Extract Resource Type (si vous ne la trouvez pas, appuyer sur
entrée)

[Link] 5/21
09/12/2017 TP5 - TP eServices

Taper Collection comme nom de type de ressource et déplacer les méthodes

get et post de la fenêtre de gauche vers celle de droite

Un nouveau resourceType, appelé Collection, est créé, contenant les

méthodes get et post comme elles ont été dé nies sous la ressource /pets.
De plus, /pets est désormais de type Collection.

Répéter la procédure pour la ressource /{id}. On appellera le type Member.

Le résultat devra ressembler à ce qui suit:

Ajout de paramètres au type de ressource

Pour rendre le type de ressource créé générique, il serait plus intéressant de

paramétrer le type de réponse. Pour cela:

Remplacer le terme Pet dans Collection et Member par <<item>> .

Corriger les erreurs qui s’a chent dans les ressources Collection et Member
respectivement par { Collection: {item : Pet} } et { Member: {item :
Pet} }

Ajout d’un exemple

[Link] 6/21
09/12/2017 TP5 - TP eServices

Pour ajouter un exemple d’animal, modi er le type Pet pour qu’il soit comme suit:

types: 
Pet:
properties:
name: string
kind: string
price: number
example:
name: Snoopy
kind: Dog
price: 1000

Dé nir des paramètres pour les méthodes

Nous nous proposons d’ajouter une autre méthode de type get, qui dé nit
plusieurs paramètres.

Sous (et au même niveau que) type de /pets, taper: get:

Mettre le focus sur le get nouvellement créé

Cliquer sur Create new query parameter

Créer trois paramètres:

priceLessThan de type number

priceMoreThan de type number

petKind, de type enum;[bird, dog]

Cela devra ressembler à ce qui suit:

get: 
queryParameters:
priceLessThan: number
priceMoreThan: number
petKind:
enum:
- bird
- dog

Il est possible d’extraire certains des paramètres comme Trait, c’est à dire un
critère de ltrage. Pour cela:

[Link] 7/21
09/12/2017 TP5 - TP eServices

Mettre le focus sur le get

Cliquer sur Extract trait

Nommer le trait FiltrableByPrice, et déplacer les méthodes priceLessThan et

priceMoreThan vers la droite.

Vous remarquerez que les deux paramètres choisis ont été enlevés de la
méthode get, et remplacés par is: [FilterableByPrice].

Voici donc le résultat nal du chier RAML:

#%RAML 1.0 
traits:
FiltrableByPrice:
queryParameters:
priceLessThan: number
priceMoreThan: number
resourceTypes:
Collection:
get:
responses:
200:
body:
application/json:
type: <<item>>
post:
body:
application/json:
type: <<item>>
Member:
delete:
responses:
204:
put:
body:
application/json:
type: <<item>>
title: Pet Shop
version: v1
baseUri: /petshop
types:
Pet:
properties:
name: string
kind: string
price: number

[Link] 8/21
09/12/2017 TP5 - TP eServices

example:
name: Snoopy
kind: Dog
price: 1000
/pets:
type: { Collection: {item : Pet} }
get:
queryParameters:
petKind:
enum:
- bird
- dog
is: [FiltrableByPrice]
/{id}:
type: { Member: {item : Pet} }

Extraction de la librairie

Pour extraire les types dé nis et les représenter dans une entité réutilisable:

Mettre le focus en dehors de toutes les structures, par exemple sur title

Cliquer sur Extract Library

Appeler la librarie PetTypes

Déplacer Pet, Collection et Member vers le panel de droite

Cliquer sur Extract

Un nouveau chier contenant les trois types sélectionnés a été créé, puis inclus
comme référence dans notre chier principal.

API Management avec Anypoint Studio

Anypoint Platform

Anypoint [[Link] est une

plateforme développée par l’entreprise Mulesoft qui offre les outils nécessaires
pour la gestion d’APIs. Anypoint est classée par Gartner dans son Magic
Quadrant dans la rubrique “Application Services Governance” d’Avril 2015 parmi
les leaders du marché du API Management.

[Link] 9/21
09/12/2017 TP5 - TP eServices

Première Application

Une fois Anypoint Studio téléchargé et installé, créer un nouveau projet, qu’on
appellera PremiereApplication, et choisir Mule Server comme Runtime
Environment.
La fenêtre obtenue a l’allure suivante:

[Link] 10/21
09/12/2017 TP5 - TP eServices

 Attention
Anypoint Studio version 6.4.1 ne fonctionne qu'avec au plus JDK 1.8.0_151!

Nous allons commencer par créer une simple application qui a che un message
dans un navigateur.

À partir de la palette, glisser-déplacer les éléments graphiques suivants dans

le canevas:

HTTP: permet de se connecter aux ressources web via HTTP ou HTTPS.

Set Payload: modi e le message a ché (payload) en "Hello World!".

Votre ux aura l’allure suivante:

Con gurer votre composant HTTP :

[Link] 11/21
09/12/2017 TP5 - TP eServices

Ajouter une nouvelle Connector Con guration

Garder les options par défaut. Votre hôte se lancera à l’URL [Link]:8081

Con gurer le composant Set Payload:

Remplacer la valeur de l’élément Value par Hello World!

Lancer votre application : Run -> Run As -> Mule Application. La console
devrait a cher un message comme suit:

Dans un navigateur, taper l'adresse: [Link]:8081. Le message suivant devra

s'a cher:

Gestion des APIs avec APIKit

APIKit est un toolkit open source spécialement créé pour faciliter

l’implémentation d’APIs REST, en renforçant les bonnes pratiques de création
d’APIs.

Nous allons pour cela exposer l'API REST que nous avons créé dans le TP
précédent [../tp4/], grâce aux microservices Spring.

CRÉATION D'UN FICHIER RAML POUR LE MICROSERVICE

[Link] 12/21
09/12/2017 TP5 - TP eServices

Pour représenter le microservice "ProductService", créer le chier [Link]

suivant avec Atom:

#%RAML 1.0 
title: Micro-API
version: v1
baseUri: [Link]
/products:
get:
description: List of all the products
responses:
200:
body:
application/json:
example: !include [Link]

Rajouter également (dans le même répertoire) un chier [Link],

où vous allez trouver un exemple de produits, tel qu'ils sont représentés par votre
service sur [Link] . Cela devrait
ressembler à ce qui suit:

{ 
"_embedded": {
"products": [
{
"name": "Sample Product",
"_links": {
"self": {
"href": "[Link]
},
"product": {
"href": "[Link]
}
}
}
]
},
"_links": {
"self": {
"href": "[Link]
"templated": true
},
"profile": {
"href": "[Link]
},

[Link] 13/21
09/12/2017 TP5 - TP eServices

"search": {
"href": "[Link]
}
},
"page": {
"size": 20,
"totalElements": 3,
"totalPages": 1,
"number": 0
}
}

NOUVEAU PROJET DE API MANAGEMENT

Créer un nouveau projet qu’on appellera API_Project:

Choisir comme environnement d’exécution Mule Server.

Cocher la case Add APIKit components et entrer votre chier [Link].

Un nouveau projet sera créé avec les chiers [Link] et [Link]

ajouté sous le répertoire src/main/api, ainsi que des ux de gestion des
différentes méthodes ajoutées par défaut dans le canevas. Vous retrouverez
notamment:

[Link] 14/21
09/12/2017 TP5 - TP eServices

Flux Description Figure

api-main Flux principal, dé nissant un point d’accès

HTTP, un routeur APIKit et une référence à
une stratégie d'exception

action:/ressource:api- Un Backend ow pour chaque paire de

con g ressource/action dans le chier RAML. Par
exemple, get:/products:api-con g
représente l’action get de la ressource
products

Exception Strategy Flux fournis par Studio pour con gurer les
Mapping messages d’erreur dans un format HTTP-
status-code-friendly

CONFIGURATION DU FLUX PRINCIPAL

Dans les propriétés du composant HTTP, dé nir le Path par: /prod-

services/*.

Dans le Connector Con guration, cliquer sur l'icône , puis cliquer sur OK
pour valider le host ([Link]) et le port (8081)

 Remarque
Vous pouvez changer ici le port dé ni par défaut, pour éviter les con its avec vos
microservices.

Lancer le projet comme Mule Project. Une APIKit Console s'a che comme suit:

[Link] 15/21
09/12/2017 TP5 - TP eServices

Pour tester votre API, cliquer par exemple sur le bouton GET devant la ressource
/products. la Console a chera alors la réponse (le produit Sample Product), qui a
été dé nie comme exemple dans le chier RAML de départ.

Pour visualiser le résultat sur le navigateur, taper le chemin de la requête comme

suit:

[Link] 

Vous obtiendrez le résultat suivant:

[Link] 16/21
09/12/2017 TP5 - TP eServices

Mapping de l'API avec votre microservice ProductService

Pour relier votre API créée avec le microservice Proxy (créé dans le TP
précédent), et qui est déployé à l'adresse suivante:

[Link] 

Supprimer le Set Payload du ow : get:/products:api-con g

Ajouter un connecteur HTTP dans la partie Source

Le con gurer comme suit:

Path: /prod-services

Cliquer sur puis sur OK pour valider le hôte et port.

Ajouter un connecteur HTTP dans la partie Process

Le con gurer comme suit:

Devant Connector Con guration, cliquer sur pour ajouter une

nouvelle con guration.

Cela représente les informations du service auquel on va accéder.

Dé nir le Host par localhost, le port par 9999, et le base path par

[Link] 17/21
09/12/2017 TP5 - TP eServices

/product-service

Cliquer sur OK pour valider

Dans la partie URL Settings, dé nir :

Path: /products

Method: Get

Sauvegarder, et lancer le service.

Tester le service sur le navigateur avec l'URL:

[Link] . Vous obtiendrez la liste complète des
produits, tels que retournés par le service ProductService initial, comme suit:

{ 
"_embedded": {
"products": [
{
"name": "Pencil",
"_links": {
"self": {
"href": "[Link]
},
"product": {
"href": "[Link]
}
}
},
{
"name": "Book",
"_links": {
"self": {
"href": "[Link]
},
"product": {
"href": "[Link]
}
}
},
{
"name": "Eraser",
"_links": {
"self": {
"href": "[Link]
},
"product": {

[Link] 18/21
09/12/2017 TP5 - TP eServices

"href": "[Link]
}
}
}
]
},
"_links": {
"self": {
"href": "[Link]
"templated": true
},
"profile": {
"href": "[Link]
},
"search": {
"href": "[Link]
}
},
"page": {
"size": 20,
"totalElements": 3,
"totalPages": 1,
"number": 0
}
}

Transformation du résultat du microservice ProductService

Si vous désirez retourner un résultat différent du Microservice initial, en ne

laissant par exemple que les noms des produits, sans tous les autres éléments
et liens supplémentaires, utiliser un objet Transform Message

Copier le ow get:/products pour créer un autre ow identique

Modi er le Path du connecteur HTTP source, pour /prod-services/names

Rajouter un objet Transform Message juste après le connecteur HTTP de

droite (celui de la partie Process). Le ow devra ressembler à ce qui suit:

[Link] 19/21
09/12/2017 TP5 - TP eServices

Con gurer l'objet Transform Message:

L'interface suivante représente les mappings à faire entre les entrées du

service et sa sortie.

Cliquer sur De ne Metadata du payload en entrée (à gauche) gauche)

Cliquer sur Add

Entrer le nom du type en entrée, par exemple products

Indiquer comme type JSON

Indiquer dans la liste déroulante suivante que le chier donné est un

Example, puis choisir le chier [Link] que vous aviez
créé.

Cliquer sur Select. Le schéma du chier donné est chargé dans la partie
Input de Transform Message.

Pour représenter le format de sortie désiré, créer un chier appelé

[Link] à l'endroit de votre préférence sur votre ordinateur.

Saisir le contenu suivant dans [Link]:

{"name":"prod"} 

[Link] 20/21
09/12/2017 TP5 - TP eServices

Cliquer sur De ne Metadata de sortie (à droite).

Ajouter un nouveau type que vous appellerez names

Dé nir comme type Json et charger le chier [Link] que vous

venez de créer.

Valider.

Maintenant que les deux schémas (entrée et sortie) sont dé nis, créer
les associations de votre choix. Dans notre cas, nous allons associer le
champ _embedded.[Link] en entrée au champ name en sortie,
comme suit:

Sauvegarder, et lancer le service.

Pour tester le service, lancer dans un navigateur: [Link]

services/names . Vous obtiendrez le résultat suivant:

{ 
"name": [
"Pencil",
"Book",
"Eraser"
]
}

[Link] 21/21