Web APIs / Web Services

Plusieurs technologies pour faire des services web en fonction du type de service que l’on veut fournir au client.

REST vs SOAP

Souvent 2 technologies s’oppose:

SOAP

SOAP est une technologie pas seulement Web (HTTP, SMTP, UDP, TCP, …) dédiée à la mise en place d’outils de manipulation de services. SOAP ne donne pas accès a des données, il donne accès à des services/actions dans une application serveur exposée.

SOAP utilise un langage XML normalisé (WSDL) pour décrire les services à utiliser et les actions à exécuter.

switchProtocol(Protocol)
upgradeAccountToPremium(User)
resendAuthentificationToken(User, Token)
POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

<?xml version="1.0"?>

<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">

<soap:Body xmlns:m="http://www.example.org/stock">
  <m:GetStockPrice>
    <m:StockName>IBM</m:StockName>
  </m:GetStockPrice>
</soap:Body>

</soap:Envelope>

L’extensibilité offre de nouvelles fonctionnalités (sécurité, atomicité, etc..)

REST

REST est une technologie Web dédiée à la mise à disposition d’une interface publique (API) pour l’accès et la manipulation (CRUD) de données.

REST ne fonctionne qu’avec HTTP(s) et utilise ses mécanismes (URI) mais ne limite pas les formats de données.

getUserInformation(UserId)
addProductToBasket(ProductId, BasketId)

Les requêtes REST sont sans état (stateless). On peut décrire une API REST avec les mécanismes de HTTP (méthodes, URI, codes de retour).

Par exemple on peut utiliser un outil comme Swagger pour :

Pros / Cons

GraphQL

Facebook propose GraphQL, une approche proche de REST avec les avantages (requêtes complexes) de SOAP. GraphQL est un langage de description qui permet au client de décrire le type de réponse qu’il désire recevoir du server.

Les outils SWAGGER

Swagger propose plusieurs outils pour nous aider a créer des API cohérentes et maintenables.

D’abord on nous propose de concevoir des APIs avec une nomenclature fixée. Swagger est à l’origine de la spécification OpenAPI.

Pour concevoir une API Swagger nous propose un éditeur qui valide la saisie. Il peut être utilisé en ligne ou être téléchargé et exécuté en local à partir les sources ou via docker:

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

Attention il y a 3 façons de spécifier des paramètre ou d’envoyer des données :

curl -X GET --header 'Accept: application/json' 'https://api.example.com/1.0.0/ping'

On peut aussi tester avec un script JS qui utilise le client généré automatiquement par Swagger.