NOTE: Article in Progress

1. Web Services

Web services

1.1. Introduction

  1. Human-machine interaction
    • client-server architecture
    • URL rewriting
  2. Machine-machine interaction
    • REST architecture style
  3. API documentation

Interaction homme-machine

Human-machine interaction

1.2 URL choice

URL

https://www.example.com/index.html

ou

https://www.example.com/index.php

ou

https://www.example.com/
https://www.example.com/index.php?lang=fr
https://www.example.com/index.php?lang=en
https://www.example.com/index.php?lang=es

ou

https://www.example.com/fr/index.php
https://www.example.com/en/index.php
https://www.example.com/es/index.php
https://www.example.com/fr/index.php
https://www.example.com/en/index.php
https://www.example.com/es/index.php

ou

https://www.example.com/fr/
https://www.example.com/en/
https://www.example.com/es/
https://www.example.com/index.php?operation=listStudents

ou

https://www.example.com/students/ https://www.example.com/index.php?operation=showStudent
https://www.example.com/index.php?operation=AddStudent
https://www.example.com/index.php?operation=deleteStudent
https://www.example.com/index.php?operation=updateStudent

ou

https://www.example.com/students/1/

1.3.URL rewriting

Installation d'apache

$ sudo apt install apache2 php7.0 libapache2-mod-php7.0

Activation de réécriture

$ sudo a2enmod rewrite
$ sudo service apache2 restart

Vérification

<?php
 phpinfo()
?>

screenshot of php mod_rewrite enabled

Configuration (Activation des fichiers .htaccess)

Vérifier le fichier /etc/apache2/sites-available/000-default.conf

DocumentRoot /var/www/html
..
<Directory "/var/www/html">
 AllowOverride All
</Directory>

Redémarrer apache2

$ sudo service apache2 restart

Redirection transparente vers index.php

.htaccess

DirectoryIndex index.php

Redirection transparente vers index.php

.htaccess

DirectoryIndex accueil.php

Redirection transparente vers index.php

.htaccess

DirectoryIndex accueil.php index.php

.htaccess

RewriteEngine on
RewriteRule ^test.html$ /index.php

.htaccess

RewriteEngine on
RewriteRule "^.+.html$" /index.php

.htaccess

RewriteEngine on
ErrorDocument 404 /404.php
RewriteRule "^(.+)/index.php$" /index.php?lang=$1

.htaccess

RewriteEngine on
RewriteRule "^(.+)/index.html$" /index.php?lang=$1

.htaccess

RewriteEngine on
RewriteRule ^students/(.+)/$ /students/index.php?id=$1
RewriteRule ^students/(.+)/(.+)$ /students/index.php?id=$1&param=$2

Erreur ressource non trouvée

.htaccess

RewriteEngine on
ErrorDocument 404 /404.php

1.4. Retrieving values from a HTML form

     <fieldset>
       <legend>Etudiant.e</legend>
        <div>
         <label for="nom">Nom</label><input type="text" id="nom" name="nom"/>
        </div> <div>
         <label for="prenom">Prénom</label><input type="text" name="prenom"/>
        </div> <div>
         <label for="prenom">Diplôme</label>
         <select id="diplome" name="diplome">
           <option>IRC</option>
           <option>ETI</option>
         </select>
        </div>
     </fieldset>
   

Récupération des valeurs

Etudiant.e

method="get"

     <form action=request.php" method="get" >
       <fieldset>
       ...
       </fieldset>
       <button type="submit">Submit</button>
     </form>
   
<?php
$method = $_SERVER['REQUEST_METHOD'];
echo "method: ".$method;
?>

method="get"

     <form action=request.php" method="get" >
       <fieldset>
       ...
       </fieldset>
       <button type="submit">Submit</button>
     </form>
   

URL (navigateur) et l'affichage sur le serveur

      http://localhost/request.php?nom=aple&prenom=mango&diplome=IRC
      method: GET
   

method="post"

     <form action=request.php" method="post" >
       <fieldset>
       ...
       </fieldset>
       <button type="submit">Submit</button>
     </form>
   

URL (navigateur) et l'affichage sur le serveur

      http://localhost/request.php
      method: POST
   

method="put"

     <form action=request.php" method="PUT" >
       <fieldset>
       ...
       </fieldset>
       <button type="submit">Submit</button>
     </form>
   

URL (navigateur) et l'affichage sur le serveur

      http://localhost/request.php?nom=aple&prenom=mango&diplome=IRC
      method: GET
   

method="delete"

     <form action=request.php" method="delete" >
       <fieldset>
       ...
       </fieldset>
       <button type="submit">Submit</button>
     </form>
   

URL (navigateur) et l'affichage sur le serveur

      http://localhost/request.php?nom=aple&prenom=mango&diplome=IRC
      method: GET
   

1.5. Example

.htaccess

RewriteEngine on
ErrorDocument 404 /404.php
RewriteRule "^(.+)/index.php$" /index.php?lang=$1

Récupération des valeurs GET: PHP

<?php
$language = "fr";
if($_GET["lang"]) {
  $language = $_GET["lang"];
}
if($language == "en") {
  echo "Hello!";
}
else if($language == "fr") {
  echo "Bonjour!";
}
?>

Récupération des valeurs GET: PHP

<?php
if($_GET["nom"] && $_GET["prenom"] ) {
  echo "Bonjour! ".$_GET["prenom"]." ".$_GET["nom"];
}
?>

POST: PHP

<?php
if($_POST["nom"] && $_POST["prenom"] ) {
  echo "Bonjour! ".$_POST["prenom"]." ".$_POST["nom"];
}
?>

PUT, DELETE: PHP

<?php
if($_GET["nom"] && $_GET["prenom"] ) {
  echo "Bonjour! ".$_GET["prenom"]." ".$_GET["nom"];
}
?>

GET, POST, PUT, DELETE: PHP

<?php
if(strcasecmp($_SERVER["REQUEST_METHOD"], "POST") == 0) {
  if($_POST["nom"] && $_POST["prenom"] ) {
    echo "Bonjour! ".$_POST["prenom"]." ".$_POST["nom"];
  }
}
else {
  if($_GET["nom"] && $_GET["prenom"] ) {
    echo "Bonjour! ".$_GET["prenom"]." ".$_GET["nom"];
  }
}
?>

1.6. Debugging: Logging

Enregistrement de données (Serveur Apache)

     $ tail /var/log/apache2/access.log
   
127.0.0.1 - - [14/Nov/2018:14:46:49 +0100] "GET / HTTP/1.1" 200 3477 "-"
         "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:63.0) Gecko/20100101 Firefox/63.0"
127.0.0.1 - - [14/Nov/2018:14:46:49 +0100] "GET /icons/ubuntu-logo.png HTTP/1.1" 304 180 "http://localhost/"
         "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:63.0) Gecko/20100101 Firefox/63.0"
127.0.0.1 - - [14/Nov/2018:14:46:49 +0100] "GET /favicon.ico HTTP/1.1" 404 294 "-"
         "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:63.0) Gecko/20100101 Firefox/63.0"
   
     $ tail /var/log/apache2/error.log
   
[Wed Nov 14 09:53:39.563044 2018] [mpm_prefork:notice] [pid 849]
         AH00163: Apache/2.4.29 (Ubuntu) configured -- resuming normal operations
[Wed Nov 14 09:53:39.563066 2018] [core:notice] [pid 849]
         AH00094: Command line: '/usr/sbin/apache2'
[Wed Nov 14 11:35:35.060638 2018] [mpm_prefork:notice] [pid 849]
         AH00169: caught SIGTERM, shutting down
   
LogLevel (https://httpd.apache.org/docs/2.4/mod/core.html#loglevel)
Log Format (https://httpd.apache.org/docs/2.4/mod/core.html#errorlogformat)

2. REST architecture style

2.1. REST: Contraintes

Une architecture REST doit respecter les six contraintes suivantes

  1. un architecture client-serveur
  2. Un serveur sans état
  3. Avec cache
  4. À interface uniforme
  5. En couches
  6. Code à la demande (facultatif)

1. Architecture client-serveur

2. Un serveur sans état

3. Avec cache

4. À interface uniforme

4. À interface uniforme

  1. identification des ressources
  2. manipulation des ressources par des représentations (XML, JSON etc.)
  3. messages auto-descriptifs
  4. hypermédia comme moteur d'état de l'application

4. À interface uniforme

Hypermédia en tant que moteur de l'état d'application

Un client REST n'a besoin d'aucune connaissance préalable sur la façon d'interagir avec une application ou un serveur particulier au-delà d'une compréhension générique de l'hypermédia.

5. En couches

6. Code à la demande (facultatif)

API Github (REST)

REST API of Github

RESTful Services Web

Différents niveaux [2]

  1. Niveau 0: HTTP
  2. Niveau 1: Ressources
  3. Niveau 2: Verbs HTTP (GET, POST, PUT, DELETE)
  4. Niveau 3: Hypermedia
https://www.example.com/students/
https://www.example.com/students/1/
https://www.example.com/students/1/module1/

2.2. HTTP codes

Liste des codes HTTP

  1. 1xx - Information
  2. 2xx - Succès
  3. 3xx - Redirection
  4. 4xx - Erreur du client web
  5. 5xx - Erreur du serveur / du serveur d'application

Liste des codes HTTP

Les codes les plus courants sont :

  1. 200 : succès de la requête ;
  2. 301 et 302 : redirection, respectivement permanente et temporaire ;
  3. 401 : utilisateur non authentifié ;
  4. 403 : accès refusé ;
  5. 404 : page non trouvée ;
  6. 500 et 503 : erreur serveur ;
  7. 504 : le serveur n'a pas répondu.

2.3. Creating RESTful API

cURL

  1. client URL request library : « bibliothèque de requêtes aux URL pour les clients »
$ curl example.com

cURL: en-tête (header)

$ curl -I http://localhost/index.php

Sortie

HTTP/1.1 200 OK
Date: Thu, 26 Apr 2018 18:54:18 GMT
Server: Apache/2.4.18 (Ubuntu)
Content-Length: 14
Content-Type: text/html; charset=UTF-8

cURL: GET

$ curl http://localhost/index.php $ curl -X GET http://localhost/index.php

cURL: POST

$ curl -X POST http://localhost/index.php $ curl -X POST --data 'user:abc' http://localhost/index.php $ curl -X POST -d @file.json http://localhost/index.php

cURL: PUT

$ curl -X PUT http://localhost/index.php $ curl -X PUT --data '' http://localhost/index.php $ curl -X PUT -d @file.json http://localhost/index.php

cURL: DELETE

$ curl -X DELETE http://localhost/index.php

méthode HTTP

$_SERVER['REQUEST_METHOD']

PHP: récupération de paramètres

$data = json_decode(file_get_contents('php://input'), true);

PHP:

echo http_response_code(521);

.htaccess

RewriteEngine on
ErrorDocument 404 /404.php
RewriteRule ^(.+)/$ /index.php?resource=$1
RewriteRule ^(.+)/(.+)$ /index.php?resource=$1&id=$2

3. API Documentation

REST API of Github

API Documenation

  1. Documentation lisible par l'homme
  2. Documentation lisible par machine
  3. Documentation lisible par l'homme et machine

Documentation lisible par l'homme: Développeur/Développeuse

REST API of Github
  1. lit la documentation de l'API en format texte ou HTML
  2. développe du code pour l'intégration avec les services Web
  3. ajoute code métier
REST API of Github

Documentation lisible par l'homme: Développeur/Développeuse

  1. surveille les changements de l'API
  2. Réécrit le code si l'API change

API

  1. liste des opérations (méthodes)
    • paramètres d'entrée et de sortie
    • erreurs
  2. format du messagei (json, xml etc.)
  3. mécanisme d'authentification
  4. mécanisme d'autorisation

Documentation lisible par machine: WSDL

WSDL 1.1 vs 2.0

Le WSDL (Web Services Description Language) sert à décrire

  1. le protocole de communication (SOAP RPC ou SOAP orienté message)
  2. les méthodes (opérations)
  3. le format de messages (les types de données)
  4. la localisation du service
WSDL 1.1 vs 2.0
WSDL: documentation, types, interfaces
WSDL 1.1 vs 2.0
WSDL: binding, services

WSDL Libraries

  1. Java: wsimport, WSDL4J,..
  2. Python: zeep,..

WADL (Web Application Description Language)

  1. décrit des applications REST
  2. décrit des ressources, méthodes, paramètres et réponses
WADL
WADL: ressources, méthodes, paramètres et réponses

SA-WSDL (Semantic Annotations for WSDL and XML Schema)

  1. définit un ensemble d'attributs d'extension pour WSDL et XSD
  2. permet des annotations sémantiques en utilisant des ontologies
WADL
SA-WSDL: Annotation d'un fichier WSDL
WADL
SA-WSDL: Annotation d'un fichier WSDL

hRESTS

  1. Documentation lisible par l'homme et machine
  2. utilise microformat HTML
WADL
hRESTS: microformat

References

  1. Rodríguez, Carlos, et al. REST APIs: a large-scale analysis of compliance with principles and best practices. International Conference on Web Engineering. Springer, Cham, 2016.
  2. Pautasso, Cesare. RESTful web services: principles, patterns, emerging technologies. Web Services Foundations. Springer, New York, NY, 2014. 31-51.
  3. Samuel, John, and Christophe Rey. Integration of Multiple Heterogeneous and Autonomous Web Services using Mediation Approach: Open Challenges. Journal on Advances in Theoretical and Applied Informatics 2.2 (2016): 38-46.
  4. Kopecký, J., Gomadam, K., & Vitvar, T. Hrests: an html microformat for describing restful web services. IEEE/WIC/ACM International Conference on Web Intelligence and Intelligent Agent Technology (2008), 1, 619–625. https://doi.org/10.1109/WIIAT.2008.379
  5. https://fr.wikipedia.org/wiki/Representational_state_transfer
  6. https://fr.wikipedia.org/wiki/Client%E2%80%93serveur
  7. https://fr.wikipedia.org/wiki/HATEOAS
  8. Apache Allowoverride
  9. .htaccess
  10. https://fr.wikipedia.org/wiki/CURL
  11. Form submission (W3C)
  12. https://en.wikipedia.org/wiki/Web_Services_Description_Language
  13. https://fr.wikipedia.org/wiki/Web_Services_Description_Language
  14. https://fr.wikipedia.org/wiki/Web_Application_Description_Language
  15. https://www.w3.org/Submission/wadl/
  16. https://docs.oracle.com/javase/6/docs/technotes/tools/share/wsimport.html
  17. https://sourceforge.net/projects/wsdl4j/
  18. https://pypi.org/project/zeep/