# Tour d'horizon des API REST

Au détour d'une conversation entre développeurs, vous avez certainement déjà entendu les termes "API", "REST" ou encore "SOAP", mais que peuvent bien signifier ces acronymes ?

Heureusement, je suis là pour écrire cet article qui va vous aider à y voir plus clair ! Je sais, pas besoin de me remercier ;)

## Une API ?

Non, ce n'est pas une variété de pomme.

API est un acronyme pour `Application Programming Interface` ou `Interface de Programmation d'Application` dans la langue de Molière.

"Très bien, mais ça ne nous avance pas plus pour comprendre à quoi ça sert"

En effet, c'est un peu vague comme définition...

Plus précisément, on parle d'API lorsqu'un programme informatique cherche à interagir avec un système tiers et que cette interaction se fait en respectant des règles propre au type de l'API (nous y reviendrons plus tard). On dit que ce système tiers "expose une API".

Voilà, on comprend déjà mieux à quoi sert une API ! Mais comme un exemple vaut mieux que mille mots, je vous met un cas d'utilisation concret d'une API ci-dessous.

### Exemple d'utilisation d'une API

Imaginons que je réalise une application web qui permette d'afficher tous les pokémons de chaque génération avec leurs informations: nom, image, statistiques etc...

Je pourrais très bien réaliser un fichier JSON avec toutes ces infos que j'importerai dans mon application, mais à ce jour il y a près de 1000 pokémons différents !

Le temps de travail pour réaliser ce fichier est énorme !!!

Heureusement pour moi, une API existe et elle se nomme [PokéAPI](https://pokeapi.co/).

Sur la page d'accueil, on peut voir que l'on peut récupérer toutes les informations dont nous avons besoin en tapant une URL, WOW !


Je peux donc me servir des URLs misent à disposition par cette API pour récupérer les infos en JSON dont j'ai besoin !

J'utilise une API. C'est cool non ?

## API SOAP ou API REST ?

Dans les API utilisées par les services web, on entend souvent parler d'API REST ou d'API SOAP mais quelles sont les différences entre ces deux types d'API ?

### SOAP

SOAP est un protocole d'échange d'informations basé en XML, ça ressemble à ça:


Il est composée en deux parties:

- Une enveloppe contenant les informations nécessaires au fonctionnement de son acheminement et de son traitement.
- Les informations à transmettre.

### REST

REST ou `REpresentational State Transfer` lui, n'est pas un protocole mais un style d'architecture définissant un ensemble de contraintes à utiliser pour créer des services web. Il peut retourner des réponses sous plusieurs formats : JSON, HTML ou même de l'XML.

Il existe 6 contraintes dans l'architecture REST:

- Client-Serveur: Les deux doivent fonctionner indépendamment l'un de l'autre.
- Stateless (Sans État): L'API ne conserve pas l'état de la session entre le client et elle-même, toutes les informations d'authentification doivent être renvoyés à chaque requête par le client.
- Mise en cache: Les donnèes retournées par l'API doivent pouvoir être mise en cache.
- En couches: L'API peut être subdivisée sur plusieurs serveurs pour améliorer la performance et la sécurité.
- Code à la demande (facultatif): L'API peut retourner des scripts exécutables pour modifier l'interface client.
- Interface uniforme: La contrainte la plus importante dans une API REST
- Identification des ressources dans les requêtes, pour un service web par exemple, l'URI pour récupérer les utilisateurs ressemblera à `/api/v1/users`.
- Manipulation des ressources, on doit pouvoir manipuler ou supprimer des ressources depuis le client.
- Messages auto-descriptifs, les informations retournées par une requête doivent pouvoir être facilement compréhensible.

### Quel type d'API utiliser ?

Ces deux types d'API ont chacun leurs avantages et leurs inconvénients, SOAP étant un protocole qui relie le client au serveur, une modification de l'API demande également une modification sur le client, de plus les réponses en XML sont souvent très verbeuse et donc plus lourde. REST quand à lui est plus léger et une modification dans l'API n'impactera pas le client.

Je vous recommande d'utiliser une API REST pour la plupart de vos projets. De plus, je vais maintenant approfondir le fonctionnement de l'API REST en vous montrant comment en créer une et comment générer une documentation pour celle-ci.

## Créer une API REST

### 1 - Mise en place

Pour mon exemple, je vais créer mon API avec le framework Laravel.

Je crée donc un nouveau projet Laravel: `composer create-project --prefer-dist laravel/laravel api-rest`

Une fois le projet installé, je rentre dans celui-ci: `cd api-rest`

Puis je lance le serveur local: `php artisan serve`

En ouvrant l'URL [http://127.0.0.1:8000](http://127.0.0.1:8000) vous devriez vous retrouver avec la page d'accueil par défaut de Laravel:


C'est parfait !

Maintenant, nous allons créer des Models de base de données et des Migrations pour créer les tables nécessaires à notre API dans la base de données.

Pour mon exemple, je vais créer un Model Author et un Model Book, chaque auteur pourra être relié à 0, 1 ou plusieurs livres.

C'est parti:
- `php artisan make:model Author`
- `php artisan make:model Book`

Deux fichiers ce sont créés dans le dossier `app/`:
- `Author.php`
- `Book.php`

Nous allons maintenant créer nos Migrations, qui vont nous permettre de choisir quelles colonnes seront nécessaires pour les tables Author et Book:
- `php artisan make:migration create_authors_table`
- `php artisan make:migration create_books_table`

Deux fichiers se sont créés dans le dossier `database/migrations/`:
- `XXXX_XX_XX_XXXXXX_create_authors_table.php`
- `XXXX_XX_XX_XXXXXX_create_books_table.php`

Commençons par modifier le fichier `XXXX_XX_XX_XXXXXX_create_authors_table.php`, un auteur aura besoin d'un prénom et d'un nom:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateAuthorsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('authors', function (Blueprint $table) {
            $table->id();
            // Début
            $table->string('firstname');
            $table->string('lastname');
            // Fin
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('authors');
    }
}

Modifions maintenant `XXXX_XX_XX_XXXXXX_create_books_table.php`, un livre aura besoin d'un titre et d'un auteur:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateBooksTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('books', function (Blueprint $table) {
            $table->id();
            // Début
            $table->string('title');
            $table->foreignId('author_id');
            // Fin
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('books');
    }
}

Nous allons maintenant créer des auteurs et des livres à l'aide d'un `seeder` Laravel ! Pour ce faire, nous allons modifier le fichier `database/seeds/DatabaseSeeder.php` comme ceci:

<?php

use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Database\Seeder;
// Début
use App\Author;
use App\Book;
// Fin

class DatabaseSeeder extends Seeder
{
    use RefreshDatabase;

    /**
     * Seed the application's database.
     *
     * @return void
     */
    public function run()
    {
        // Début
        $author = Author::create([
            "firstname" => "Maxime",
            "lastname" => "Chattam",
        ]);

        Book::create([
            "title" => "Le Signal",
            "author_id" => $author->id,
        ]);

        Book::create([
            "title" => "Un(e)secte",
            "author_id" => $author->id,
        ]);

        $author = Author::create([
            "firstname" => "Jules",
            "lastname" => "Vernes",
        ]);

        Book::create([
            "title" => "Vingt Mille Lieues sous les mers",
            "author_id" => $author->id,
        ]);

        Book::create([
            "title" => "Le Tour du monde en quatre-vingts jours",
            "author_id" => $author->id,
        ]);

        $author = Author::create([
            "firstname" => "Victor",
            "lastname" => "Hugo",
        ]);

        Book::create([
            "title" => "Les misérables",
            "author_id" => $author->id,
        ]);

        Book::create([
            "title" => "Notre-Dame de Paris",
            "author_id" => $author->id,
        ]);
        // Fin
    }
}

Nous avons tout ce dont nous avons besoin pour générer les tables, les colonnes et quelques données dans notre base de données pour commencer notre API.

Avant de lancer les commandes qui vont nous permettre de remplir notre base de données, il faut indiquer à Laravel où se trouve celle-ci, pour cela, je vous invite à modifier le fichier `.env` avec les informations de votre base de données locale.

...
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=apitest
DB_USERNAME=root
DB_PASSWORD=
...

Ensuite, vous pouvez lancer les commandes:
- `php artisan config:cache` (pour mettre à jour la nouvelle configuration de votre fichier `.env`).
- `php artisan migrate` (pour créer les tables et les colonnes que l'on à indiqué dans nos migrations).
- `php artisan db:seed` (pour injecter les données de notre seeder).

Nous avons désormais un jeu de données avec lesquels jouer pour tester notre API !

### 2 - CRUD

Nous allons désormais réaliser un CRUD avec nos données, mais tout d'abord, qu'est-ce qu'un CRUD ?

CRUD est un acronyme pour `Create, Read, Update, Delete` ou `Créer, Lire, Mettre à jour, Supprimer` en français. Ce qui veut dire que notre API devra permettre de faire tout ceci avec nos auteurs et nos livres.

Pour réaliser ce CRUD, nous allons d'abord créer des routes qui vont correspondre aux URLs qu'exposeront notre API.

Pour cela, on doit modifier le fichier `/routes/api.php`.

Dans ce fichier, nous allons définir les routes dont nous aurons besoin pour notre CRUD:
- CREATE:
- `POST /api/authors` et `POST /api/books` pour créer nos auteurs et nos livres.
- READ:
- `GET /api/authors` et `GET /api/books` pour récupérer les auteurs et les livres.
- `GET /api/authors/{id}` et `GET /api/books/{id}` pour récupérer un auteur ou un livre.
- UPDATE:
- `PUT /api/authors/{id}` et `PUT /api/books/{id}` pour modifier les auteurs et les livres.
- DELETE:
- `DELETE /api/authors/{id}` et `DELETE /api/books/{id}` pour supprimer les auteurs et les livres.

Voici à quoi ressemble le fichier `/routes/api.php` après l'ajout des routes:

<?php

use App\Author;
use App\Book;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| Here is where you can register API routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| is assigned the "api" middleware group. Enjoy building your API!
|
*/

// CREATE Début

Route::post('/authors', function (Request $request) {
    $author = Author::create([
        'firstname' => $request->firstname,
        'lastname' => $request->lastname,
    ]);

    return $author;
});

Route::post('/books', function (Request $request) {
    $book = Book::create([
        'title' => $request->title,
        'author_id' => $request->author_id,
    ]);

    return $book;
});

// CREATE Fin

// READ Début

Route::get('/authors', function () {
    return Author::all();
});

Route::get('/authors/{author}', function (Author $author) {
    return $author;
});

Route::get('/books', function () {
    return Book::all();
});

Route::get('/books/{book}', function (Book $book) {
    return $book;
});

// READ Fin

// UPDATE Début

Route::put('/authors/{author}', function (Request $request, Author $author) {
    $author->firstname = $request->has('firstname') ? $request->firstname : $author->firstname;
    $author->lastname = $request->has('lastname') ? $request->lastname : $author->lastname;
    $author->save();

    return $author;
});

Route::put('/books/{book}', function (Request $request, Book $book) {
    $book->title = $request->has('title') ? $request->title : $book->title;
    $book->author_id = $request->has('author_id') ? $request->author_id : $book->author_id;
    $book->save();

    return $book;
});

// UPDATE Fin

// DELETE Début

Route::delete('/authors/{author}', function (Author $author) {
    $author->delete();

    return $author;
});

Route::delete('/books/{book}', function (Book $book) {
    $book->delete();

    return $book;
});

// DELETE Fin

Pour mes tests, je vais utiliser le logiciel Postman qui est un client pour API. Il en existe d'autres tels que Insomnia ou Fiddler.

Le but de ces logiciels et de pouvoir réaliser des requêtes pour pouvoir tester rapidement le fonctionnement d'une API par exemple.

#### 1 - Création

Je vais utiliser les routes que nous avons définies ci-dessus et créer un nouvel auteur par exemple:


Une simple requête POST avec deux paramètres `firstname` et `lastname` et notre nouvel auteur est créé en DB.

#### 2 - Récupération des données

Je vais utiliser les routes que nous avons définies ci-dessus et récupèrer la liste de tous les livres par exemple:


C'est aussi simple que cela, nous pouvons désormais récupèrer tous les livres de notre base de données. Si nous voulons récupérer tous les auteurs, c'est simple, il suffit de remplacer `/books` par `/authors` dans l'URL de notre requête.

Si je veux récupérer l'auteur que j'ai créé précedemment, il me suffit de rajouter son id dans la requête:


#### 3 - Édition des données

Je vais utiliser les routes que nous avons définies ci-dessus et modifier l'auteur que j'ai créé précedemment:


Pour cela, j'ai effectuer une requête `PUT` et j'ai renseigner l'id de l'auteur que je souhaitais modifier dans l'URL de la requête. J'ai également ajouter les paramètres `firstname` et `lastname` avec les nouvelles valeurs voulues.

#### 4 - Supression des donnès

Remplacer Frank Herbert par Stephenie Meyer...

Pour nous décharger de cette hérésie, nous allons supprimer cet auteur (de la DB bien sûr).

Je vais utiliser les routes que nous avons définies ci-dessus et supprimer l'auteur:


Vérifions:


Elle n'est plus la :D

### 3 - Générer une documentation

Créer une API c'est super mais comment permettre à nos clients de savoir quels routes sont disponibles, quels actions sont réalisables, quels sont les paramètres à fournir, etc...

Le mieux pour résoudre ce problème et de créer une documentation.

Pour notre petit exemple, la documentation n'est pas très longue à rédiger à la main, mais si l'application est amené à ce développer, le mieux est d'utiliser un générateur de documentation tel que Swagger ou OpenAPI.

Le fonctionnement est simple, lors de la création de vos Models et de vos Controllers dans Laravel, il faudra rajouter un bloc de commentaire pour expliquer ce que fait votre API:

<?php

/**
 * @OA\Post(
 *     path="/authors",
 *     tags={"author"},
 *     summary="Create author",
 *     description="This create an author in the database",
 *     operationId="createAuthor",
 *     @OA\Response(
 *         response="default",
 *         description="successful operation"
 *     ),
 *     @OA\RequestBody(
 *         description="Create user object",
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/Author")
 *     )
 * )
 */
 public function createAuthor(Request $request) {
     // ...
 }

Vous pourrez retrouver la documentation pour savoir rédiger ces blocs de commentaires ici: [lien vers la documentation Swagger/OpenAPI](https://swagger.io/specification/)

Pour expliquer très succintement ce qu'est OpenAPI, c'est un standard qui permet de pérenniser le développement des API car chaque personne à sa manière de créer son API.

Vous pourrez retrouver les standards d'OpenAPI [ici](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)

Ensuite, grâce à cette documentation générée, vous pourrez accéder à un url qui contient toutes les actions que votre API permet de réaliser.

[Exemple de documentation générée](https://petstore.swagger.io/)

# Conclusion

Lors de cette article, nous avons défini ce qu'était une API ainsi que les deux types d'API les plus répandues dans le web, SOAP et REST.

Nous avons également vu comment réaliser une API REST avec Laravel et appris que nous pouvons générer une documentation pour celle-ci à l'aide d'annotations dans notre code.

Malgré tout, je sais que la notion d'API peut rester vague pour les débutants et je vous invite à tester, créer et modifier des API par vous même.

Voici deux sites sur lesquels vous pourrez retrouver une liste d'API libres avec lesquelles vous pourrez vous entrainer: [github/public-apis](https://github.com/public-apis/public-apis) et [api.gouv.fr](https://api.gouv.fr/).