Spring REST

Dans cette quête, tu vas découvrir REST (REpresentational State Transfer), un style d'architecture permettant de créer des services web. Après avoir fait un tour des concepts fondamentaux de celui-ci, tu vas apprendre à concevoir une application Spring RESTful (c'est-à-dire répondant aux critères du style REST) qui va te permettre de lire ou de modifier des informations dans une base de données (BDD).

Objectifs

• Connaître les concepts fondamentaux de l'architecture REST
• Savoir réaliser une application Spring RESTful communiquant avec une BDD
• Savoir effectuer des requêtes client -> serveur via le logiciel Postman

REST : concepts fondamentaux

Dans cette étape, tu vas te familiariser avec les concepts fondamentaux de REST pas-à-pas. Pour cela, consulte les ressources.

REST : création d'une application Spring RESTful

Pour apprendre à concevoir une application Spring respectant les normes de l'architecture REST, tu vas suivre un tutoriel découpé en 3 parties.

1. Démarrage du projet

Suis le guide Building a Spring Boot REST API - Part I (donné en ressource juste en dessous) à partir de l'étape « Controller, the C in MVC ». En effet, l'auteur du tutoriel initialise son projet à la main. En ce qui te concerne, tu peux le faire via la page Spring Initializr, en choisissant comme dépendance "Web". Génère le projet, télécharge le zip, extrais-le et importe le dossier obtenu dans ton IDE.

2. Création de la classe Blog et REST

Suis le guide Building a Spring Boot REST API - Part II (donné en ressource juste en dessous), mais saute l'étape « The Blog Data ». L'auteur y réalise un mockup de données * (un jeu de données factice*) pour ses données ; suis-le si tu le souhaites, mais cette étape n'est pas obligatoire dans le processus. Reprends le tutoriel à partir de l'étape « REST Endpoints ». En ce qui concerne l'étape « The Controller », saute-la également.

3. Création de la BDD et du controller

Suis le guide Building a Spring Boot REST API - Part III (donné en ressource juste en dessous). Pour le fichier application.properties (donné à l'étape « Setting Connection Properties »), ajoute spring.jpa.hibernate.ddl-auto = create-drop. De cette façon, à chaque fois que tu lanceras ton application Spring, les données de ta table MySQL seront écrasées pour faire place aux nouvelles, ce qui facilitera les manipulations que tu vas faire sur ton application.

À l'étape « Converting Blog To Entity (@Entity) », utilise @GeneratedValue(strategy = GenerationType.IDENTITY) plutôt que @GeneratedValue(strategy = GenerationType.AUTO) . Si tu souhaites creuser la question des Generation types tu trouveras ton bonheur sur cette ressource

Une fois arrivé(e) à l'étape « The Controller », utilise ce modèle de controller plutôt que celui du tutoriel :

package [nom de ton package]

import org.springframework.web.bind.annotation.RestController;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

@RestController
public class BlogController {

    @Autowired
    BlogRespository blogRespository;

    @GetMapping("/blogs")
    public List<Blog> index(){
        return blogRespository.findAll();
    }

    @GetMapping("/blogs/{id}")
    public Blog show(@PathVariable int id){
        return blogRespository.findById(id).get();
    }

    @PostMapping("/blogs/search")
    public List<Blog> search(@RequestBody Map<String, String> body){
        String searchTerm = body.get("text");
        return blogRespository.findByTitleContainingOrContentContaining(searchTerm, searchTerm);
    }

    @PostMapping("/blogs")
    public Blog create(@RequestBody Blog blog){
        return blogRespository.save(blog);
    }

    @PutMapping("/blogs/{id}")
    public Blog update(@PathVariable int id, @RequestBody Blog blog){
        // getting blog
        Blog blogToUpdate = blogRespository.findById(id).get();
        blogToUpdate.setTitle(blog.getTitle());
        blogToUpdate.setContent(blog.getContent());
        return blogRespository.save(blogToUpdate);
    }

    @DeleteMapping("blogs/{id}")
    public boolean delete(@PathVariable int id){
        blogRespository.deleteById(id);
        return true;
    }
}

En effet, comme tu peux le voir dans le tutoriel, l'auteur convertit le JSON reçu par l'application Spring depuis le client en un objet de type Map<String, String>. Or, il est possible (et plus simple) de convertir le JSON en bon vieil objet Java (Plain old Java Object en anglais, ou POJO, en anglais), puis d'utiliser l'objet pour le modifier (via ses setters/getters) ou pour le stocker en BDD.

Seul le cas suivant

@PostMapping("/blog/search")
public List<Blog> search(@RequestBody Map<String, String> body){
    String searchTerm = body.get("text");
    return blogRespository.findByTitleContainingOrContentContaining(searchTerm, searchTerm);
}

présente une utilisation intéressante de la conversion en map. Une approche alternative consisterait à créer une classe SearchTerm ayant pour unique attribut text (et dans ce cas, il faudrait que le champ utilisé dans le JSON s'appelle nécessairement text). Dans le cas de la conversion en map, il n'y a pas besoin de créer une classe qui n'aura d'autre utilité que cette fonctionnalité de recherche.

De plus, une convention répandue est d'utiliser le pluriel dans le nom des URL, contrairement à ce que fait l'auteur.

Test de l'application avec le logiciel Postman

Postman est un logiciel qui va te permettre de tester très facilement les API que tu développes. Installe-le sur ton ordinateur, puis consulte la ressource « Postman - Getting started » pour voir (en 2 minutes chrono) comment l'utiliser.

Lance ton application Spring (ligne de commande mvn spring-boot:run). Sers-toi ensuite de Postman pour tester l'API que tu viens de créer au sein de ton application. Si tout se passe bien, voici ce que tu devrais avoir :

Lorsque tu réalises une requête POST sur l'url localhost:8080/blogs (qui correspond, dans ton controller, à la partie annotée @PostMapping("/blogs")), Spring lit le JSON transmis (dont les champs correspondent aux attributs de la classe Blog (title et content)) et crée à partir de ce dernier un objet de classe (on peut aussi dire « de type ») Blog avant de le sauvegarder dans la BDD.

Ici, pour l'exemple, on fait une requête POST, afin de créer un objet de type Blog qui aura pour correspondance, dans la BDD, une ligne dans la table blog.

Une requête PUT permettra de mettre à jour le blog dont on passe l'id en paramètre dans l'url :

De la même façon, une requête DELETE entraînera la suppression du blog dont l'id est passé en paramètre de l'url.

Lorsqu'un JSON contenant un champ text est envoyé au serveur via une requête POST sur l'url localhost:8080/blogs/search, la valeur du champ text (ici, today) est prise comme critère de recherche dans la BDD. Seule seront envoyés, dans le JSON de réponse, les blogs qui contiennent le terme today.

Challenge

Save the library, save the world

Félicitations, tu viens d'être nommé grand bibliothécaire de la Wild Code School !

Sur le modèle de ce que tu as réalisé lors de cette quête, auras-tu l'audace de relever l'extraordinaire défi de créer une application Spring RESTful permettant de gérer les livres disponibles dans ta bibliothèque ? Pour ce faire, suis les étapes suivantes :

1. Créer une BDD MySQL et initialiser un projet Spring communiquant avec celle-ci
2. Créer une entité Book ayant pour attributs title, author et description
3. Créer un BookRepository permettant de réaliser les 4 opérations CRUD + une opération de recherche par mot-clé contenu dans le titre ou la description
4. Mettre en place un controller répondant aux critères REST
5. Tester l'application dans Postman
6. Envoyer le projet vers son dépôt distant et partager le lien en solution.

Critères de validation

• Toutes les requêtes envoyées vers l'application Spring via Postman (verbes GET, POST, PUT et DELETE) fonctionnent et renvoient des réponses cohérentes.