Comment créer une API REST au Spring Boot 2

Publication : 5 octobre 2020

Il s'agit d'un tutoriel d'introduction sur la façon de créer une API REST qui effectue des opérations CRUD. Elle permet d'obtenir, d'ajouter, de mettre à jour et de supprimer des données.

Dépendance

Vous devez ajouter la dépendance "spring-boot-starter-web", en plus de votre dépendance standard "Spring" ("spring-boot-starter-parent").

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

Explication

Une API REST a des points d'extrémité qui sont une "URL" à laquelle on peut accéder pour envoyer ou récupérer des données de l'API. Vous devez utiliser des commandes "HTTP" telles que "GET", "POST", "DELETE", "UPDATE" et autres pour communiquer avec l'API.

"GET" : Récupérez les données de l'API.
"POST" : Envoyez les données de l'API. Vous voulez ajouter un nouvel objet par exemple.
"UPDATE" : Mettre à jour les données. Vous voulez mettre à jour un objet existant.
"DELETE" : Supprimez des données. Supprimez un objet existant.

Les terminaux de l'API sont regroupés dans une classe qui est un "RestController". Une classe "RestController" est créée en utilisant l'annotation "@RestController". Par exemple : si vous souhaitez enregistrer des produits et des adresses dans votre API, vous devez créer une classe "RestController" pour les produits et une classe "RestController" pour les adresses.
Un terminal d'API pourrait charger un certain produit avec l'identifiant "1" de votre base de données. Les points terminaux d'API sont déclarés en ajoutant une annotation "Mapping" à une fonction qui a la fonctionnalité de ce point terminal d'API.
Par exemple, ces annotations "Mapping" sont disponibles :

@GetMapping("/MY_API_URL")

@PostMapping("/MY_API_URL")

@PutMapping("/MY_API_URL")

@DeleteMapping("/MY_API_URL")

Ceux-ci effectuent les opérations "HTTP" mentionnées ci-dessus. Vous ajoutez une de ces annotations à une fonction pour mettre en œuvre la fonctionnalité de cette opération.
Les paramètres sont définis par leur nom entre parenthèses dans l'"URI" et sont ajoutés aux arguments d'une fonction avec l'annotation "@PathVariable". Ils peuvent ensuite être récupérés par la fonction.
Exemple:

@GetMapping("/customer/{customerId}")
public ResponseEntity<Customer> getCustomerById(@PathVariable Long id) {
...
}

Si vous appelez l'URL de l'API avec un numéro quelconque "/client/1", la fonction "getCustomerById" sera appelée. L'annotation "GetMapping" fait correspondre l'URL de l'API à cette fonction et l'id passé "id" à la variable "Long" "id" dans l'argument de cette fonction.

Si vous voulez envoyer des données à l'API, vous devez utiliser un objet JSON dans le "corps" de la requête HTTP. Une annotation "@PostMapping" est utilisée dans ce cas. L'annotation "@RequestBody" est utilisée pour mapper un objet JSON (qui est envoyé par l'utilisateur de l'API) à la variable argument d'une fonction de l'API. Toute communication entre l'API et le client se fait par le biais d'objets JSON.
La fonction de l'API renvoie un objet "ResponseEntity" qui contient un objet et un code d'état HTTP. Si la requête "API" a réussi, l'objet demandé et le statut HTTP "200 OK" sont renvoyés.

Les annotations "Mapping" mentionnées ont également des arguments supplémentaires.
Exemple:

@PostMapping(path= "/save", consumes = "application/json", produces = "application/json")

L'argument "consumes" définit les données objet du type de données qui sont envoyées à l'API ". L'argument "produces" définit le type de données objet qui est renvoyé par l'API.

@RequestMapping(path="/users")

Vous pouvez définir un chemin de base pour les points terminaux de l'API de la classe "RestController", en utilisant cette commande.

Exemple de programmation

Il s'agit d'un exemple où un client peut être chargé, ajouté, mis à jour ou supprimé. La classe "CustomerService" est utilisée pour accéder aux méthodes qui effectuent les opérations de la base de données. La classe modèle " Customer " enregistre un client avec des champs tels que " customerId ", " companyName ", " forename " et plus encore.

@RestController
public class CustomerController {

    @Autowired
    private CustomerService customerService;
    private final String BASE_API_URL = "/api/customer";

    /**
     * Get all customers. HTTP GET command.
     *
     * @return
     */    
    @GetMapping(BASE_API_URL + "/all")
    public ResponseEntity<List<Customer>> getAllCustomer() {
        List<Customer> customerList = this.customerService.getAllCustomer();
        if (!CollectionUtils.isEmpty(customerList)) {
            return status(HttpStatus.OK).body(customerList);
        } else {
            return status(HttpStatus.BAD_REQUEST).body(new ArrayList<Customer>());
        }
    }

    /**
     * Get a customer with a certain id. HTTP GET command.
     *
     * @return
     */
    @GetMapping(BASE_API_URL + "/get/byEmail/{email}")
    public ResponseEntity<Customer> getOwnerByEmail(@PathVariable String email) {
        try {
            return status(HttpStatus.OK).body(this.customerService.getCustomerByEmail(email));
        } catch (DataValueNotFoundException e) {
            return status(HttpStatus.BAD_REQUEST).body(new Customer());
        }
    }

    /**
     * Add a customer. HTTP POST command. 
     * @param newCustomer
     * @return 
     */
    @PostMapping(BASE_API_URL + "/add")
    public ResponseEntity<String> addCustomer(@RequestBody Customer newCustomer) {
        int resultCode = this.customerService.save(newCustomer);

        switch (resultCode) {
            case 0:
                return ResponseEntity.ok("OK. Customer was added successfully.");
            case 1:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("ERROR. Customer cannot be null!");
            case 2:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("ERROR. Customer could not be saved!");
            case 3:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                        .body("ERROR. Customer E-Mail already exists! Please select another e-mail.");
            default:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("ERROR. Customer could not be saved!");
        }
    }
	
    /**
     * Update an existing customer. HTTP PUT command. 
     * @param id
     * @param customer
     * @return 
     */
    @PutMapping(BASE_API_URL + "/update/{id}")
    public ResponseEntity<String> updateOwner(@PathVariable Long id, @RequestBody Customer customer) {
        int resultCode = this.customerService.update(customer);

        switch (resultCode) {
            case 0:
                return ResponseEntity.ok("OK. Update was successful.");
            case 1:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("ERROR. Customer cannot be null!");
            case 2:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("ERROR. Customer does not exist!");
            case 3:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                        .body("ERROR. Customer E-Mail already exists! Please select another e-mail.");
            default:
                return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("ERROR. Update failed!");
        }

    }

	
     /**
      * Delete an existing customer. HTTP DELETE command. 
      * @param customerId
      * @return 
      */	
    @DeleteMapping(BASE_API_URL + "/delete/{id}")
    public ResponseEntity<String> deleteAccountType(@PathVariable Long customerId) {
        if (this.customerService.deleteById(customerId)) {
            return ResponseEntity.ok("Your customer was deleted successfully.");
        } else {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Error. Customer does not exists!");
        }
    }
}

Ici, l'API est accessible à partir de l'url de base "/api/customer" et du point d'extrémité API correspondant.
Par exemple, si vous souhaitez obtenir tous les clients, vous devez appeler cette URL API avec la commande HTTP "GET" :

/api/customer/all

Tester l'"REST API" créée

Vous pouvez utiliser l'application " Postman " pour tester votre API. Si vous souhaitez ne voir que la sortie, vous pouvez alors appeler directement l'url de l'API.

Tester la méthode de fin d'API "getAllCustomer" :