Cómo crear una API de REST en Spring Boot 2

Publicado: 05 Octubre 2020

Este es un tutorial de introducción sobre cómo crear una API de REST que realice operaciones de CRUD. Puede obtener, agregar, actualizar y borrar datos.

Dependencia

Necesitas añadir la dependencia "spring-boot-starter-web", además de tu dependencia estándar "Spring" ("spring-boot-starter-parent").

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

Explicación

Una API REST tiene puntos finales que son una "URL" a la que se puede acceder para enviar o recuperar datos de la API. Tienes que usar comandos "HTTP" como "GET", "POST", "DELETE", "UPDATE" y más para comunicarte con la API.

"GET": Recuperar datos de la API.
"POST": Enviar datos a la API. Quieres añadir un nuevo objeto, por ejemplo.
"UPDATE": Actualizar datos. Quiere actualizar un objeto existente.
"DELETE": Borrar datos. Borrar un objeto existente.

Los puntos finales de la API se agrupan en una clase que es un "RestController". Una clase "RestController" se crea utilizando la anotación "@RestController". Por ejemplo: si quiere guardar productos y direcciones en su API, entonces tiene que crear una clase "RestController" para los productos y una clase "RestController" para las direcciones.
Un endpoint de la API podría cargar un determinado producto con el id de producto "1" de su base de datos. Los endpoints de la API se declaran añadiendo una anotación de "Mapeo" a una función que tiene la funcionalidad de ese endpoint de la API.
Por ejemplo, estas anotaciones de "Mapeo" están disponibles:

@GetMapping("/MY_API_URL")

@PostMapping("/MY_API_URL")

@PutMapping("/MY_API_URL")

@DeleteMapping("/MY_API_URL")

Estos realizan las operaciones "HTTP" que se mencionan arriba. Se añade una de estas anotaciones a una función para implementar la funcionalidad de esa operación.
Los parámetros se definen por su nombre entre corchetes en la "URI" y se añaden a los argumentos de una función con la anotación "@PathVariable". Luego pueden ser recuperados por la función.
Ejemplo:

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

Si llamas a la URL de la API con cualquier número "/cliente/1", entonces se llamará a la función "getCustomerById". La anotación "GetMapping" asigna la url de la API a esta función y el id "id" pasado a la variable "id" "Long" en el argumento de esta función.

Si quieres enviar datos a la "API", entonces tienes que usar un objeto JSON en el "cuerpo" de la petición HTTP. En este caso se utiliza una anotación "@PostMapping". La anotación "@RequestBody" se utiliza para mapear un objeto JSON (que es enviado por el usuario de la API) a la variable de argumento de una función de la API. Toda la comunicación entre la API y el cliente se realiza a través de los objetos JSON.
La función del punto final de la API devuelve un objeto "ResponseEntity" que contiene un objeto y un código de estado HTTP. Si la solicitud de la "API" se ha realizado correctamente, se devuelve el objeto solicitado y el estado HTTP "200 OK".

Las anotaciones de "mapping" mencionadas también tienen argumentos adicionales.

Ejemplo:

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

El argumento "consumes" define los datos de objeto del tipo de datos que se envían a la API". "produces" define el tipo de datos de objeto que es devuelto por la API.

@RequestMapping(path="/users")

Puede definir una ruta base para los puntos finales de la API de la clase "RestController", utilizando este comando.

Ejemplo

Este es un ejemplo en el que un cliente puede ser cargado, añadido, actualizado o eliminado. La clase "CustomerService" se utiliza para acceder a los métodos que realizan las operaciones de la base de datos. La clase modelo "Customer" guarda un cliente con los campos como "customerId", "companyName", "forename" y más.

@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!");
        }
    }
}

Aquí se puede acceder a la API desde la url base "/api/customer" y el respectivo punto final de la API.
Por ejemplo, si se desea obtener todos los clientes, se llamaría a esta URL de la API con el comando HTTP "GET":