Configurar parámetros en Spring Rest API

Configurar parámetros en Spring Rest API es esencial, ya que esto facilita la transferencia de datos entre el cliente y el servidor. Los parámetros se pueden usar para enviar datos en forma de Query Strings, Headers o Request Body. En Spring, los parámetros generalmente se usan en forma de anotaciones @RequestParam, que se usan para mapear un parámetro a un parámetro de método. Además, los parámetros también se pueden usar en forma de anotaciones @PathVariable, que se usan para mapear un parámetro a un segmento de ruta. Con estas anotaciones, los parámetros se pueden usar para enviar datos hacia y desde el servidor, lo que permite aplicaciones más dinámicas y flexibles en el contexto de microservicios Spring Boot.

En el presente artículo analizamos las anotaciones que nos permiten configurar parámetros en Spring Rest API, con ejemplos.

Uso de @RequestParam

La anotación @RequestParam es una herramienta importante para manejar peticiones HTTP entrantes en Spring. Permite el mapeo de los parámetros de la petición a parámetros de método, lo que permite pasar datos de la petición al método que maneja la solicitud. Con @RequestParam, puede especificar el nombre del parámetro de petición, así como el tipo esperado del parámetro y un valor predeterminado en caso de que el parámetro no esté presente en la solicitud. El uso de @RequestParam es una forma efectiva de procesar los datos entrantes de las peticiones, lo que la convierte en una herramienta valiosa para manejar las peticiones entrantes en Spring.

1. Query parameters

Los Query Parameters en una API REST son parámetros adjuntos al final de una URL y separados de la URL por un signo de interrogación (?). Estos parámetros se pueden usar para controlar qué datos se retornan en la respuesta del endpoint, como limitar la cantidad de resultados devueltos (por ejemplo, para paginar los resultados) o especificar los campos que se incluirán en la respuesta. Los Query Parameters también se pueden usar para filtrar u ordenar datos, o para realizar cálculos u otras operaciones en los datos.

    @PostMapping("/customer")  
    public ResponseEntity<String> addCustomer(
    		@RequestParam Integer id, 
    		@RequestParam String firstName, 
    		@RequestParam String lastName, 
    		@RequestParam String location) {
    	
    	System.out.println("-> id: " + id);
    	System.out.println("-> firstName: " + firstName);
    	System.out.println("-> lastName: " + lastName);
    	System.out.println("-> location: " + location);
    	
    	return new ResponseEntity<String>("", HttpStatus.OK);
    }

Para realizar una petición con parámetros de consulta en Postman, simplemente puede agregar los parámetros al final de la URL o abrir la pestaña Params e ingresar el nombre y el valor de cada parámetro.

2. Path parameters

Los Path Parameters son valores que se pueden pasar en la URL de una solicitud a una API Spring Rest. Estos parámetros se utilizan para especificar el recurso al que se dirige la solicitud, como un ID de cuenta o un nombre de usuario. Para acceder a estos parámetros en Spring, puede usar la anotación @PathVariable para asignar el parámetro a un argumento de método.

    @PostMapping("/customer/{area}")  
    public ResponseEntity<String> addCustomer(
    		@PathVariable String area,
    		@RequestParam Integer id, 
    		@RequestParam String firstName, 
    		@RequestParam String lastName, 
    		@RequestParam String location) {
    	
    	System.out.println("-> area: " + area);
    	System.out.println("-> id: " + id);
    	System.out.println("-> firstName: " + firstName);
    	System.out.println("-> lastName: " + lastName);
    	System.out.println("-> location: " + location);
    	
    	return new ResponseEntity<String>("", HttpStatus.OK);
    }

Para realizar una petición con un Path Parameter en Postman, simplemente puede agregar el parámetro al final de la URL.

3. Request body

3.1. JSON body

Para consumir contenido en formato JSON en una API REST de Spring, puede usar un argumento de método con la anotación @RequestBody. Esta anotación indica que Spring debe deserializar el cuerpo de la petición HTTP y vincularlo a un parámetro de método. El cuerpo de la solicitud se pasa a través de HttpMessageConverter para resolver el argumento del método según el tipo de contenido de la solicitud. En el siguiente ejemplo usamos como parámetro un objeto Java al que los valores se mapearán automáticamente debido a que los nombres de propiedades de cuerpo de la petición JSON Y la clase Java son coincidentes.

El cuerpo de la petición será el siguiente:

{
    "id":"1",
    "firstName":"Juan",
    "lastName":"J",
    "location":"CABA"
}

Usaremos la siguiente clase como parámetro en el método de implementación del endpoint:

public class Customer {
	private Integer id;
	private String firstName;
	private String lastName;
	private String location;

	//getters y setters
}

Puede personalizar los nombres de los parámetros en un bean @RequestBody mediante la anotación @JsonProperty. Esta anotación le permite especificar el nombre del parámetro que debe usarse al deserializar el bean. Por ejemplo, si tienes una clase como esta:

public class Customer {

	@JsonProperty("id")
	private Integer id;
	
	@JsonProperty("first_name")
	private String firstName;
	
	@JsonProperty("last_name")
	private String lastName;
	
	@JsonProperty("location")
	private String location;

	//getters y setters
}

luego, el JSON enviado al servidor se deserializará en el objeto Customer, pero con los parámetros «first_name» y «last_name» en lugar de los parámetros predeterminados «firstName» y «lastName». Esto puede ser útil si necesita personalizar los nombres de los parámetros para que sean compatibles con otros sistemas.

En el controller, como se explicó anteriormente, se implementa el parámetro que recibirá los valores de la petición, anotado con @RequestBody:

    @PostMapping("/customer")  
    public ResponseEntity<String> addCustomer(@RequestBody Customer customer) {
    	
    	System.out.println("-> id: " + customer.getId());
    	System.out.println("-> firstName: " + customer.getFirstName());
    	System.out.println("-> lastName: " + customer.getLastName());
    	System.out.println("-> location: " + customer.getLocation());
    	
    	return new ResponseEntity<String>("", HttpStatus.OK);
    }

Para realizar una petición con JSON Body en Postman, puede usar la pestaña Body y seleccionar la opción raw. Luego, seleccione la opción JSON (aplicación/json) del menú desplegable e ingrese los datos JSON en el área de texto.

3.2. Media Type application/x-www-form-urlencoded 

Application/x-www-form-urlencoded es un Media Type de Internet que se utiliza para enviar datos desde formularios al servidor. Se utiliza al enviar formularios en línea y generalmente se envía como parte de una petición HTTP. Los datos se codifican como una cadena de pares clave/valor y se envían en el cuerpo de la petición, con el encabezado Content-Type aplicación/x-www-form-urlencoded. Este tipo de contenido está diseñado para usarse cuando se envía información que consiste principalmente en datos de texto, como el contenido de un formulario.

La clase MultiValueMap puese de anotada tanto con @RequestBody como con @RequestParam, como se muestra en los siguientes ejemplos.

    @PostMapping(
    	path = "/customer",
    	consumes = {MediaType.APPLICATION_FORM_URLENCODED_VALUE})  
    public ResponseEntity<String> addCustomer(@RequestBody MultiValueMap<String, String> customer) {
    	
    	System.out.println("-> Parametros en MultiValueMap: ");
    	System.out.println("-> id: " + customer.getFirst("id"));
    	System.out.println("-> firstName: " + customer.getFirst("firstName"));
    	System.out.println("-> lastName: " + customer.getFirst("lastName"));
    	System.out.println("-> location: " + customer.getFirst("location"));
    	
    	return new ResponseEntity<String>("", HttpStatus.OK);
    }

    @PostMapping(
    	path = "/customer",
    	consumes = {MediaType.APPLICATION_FORM_URLENCODED_VALUE})  
    public ResponseEntity<String> addCustomer(@RequestParam MultiValueMap<String, String> customer) {
    	
    	System.out.println("-> Parametros en MultiValueMap: ");
    	System.out.println("-> id: " + customer.getFirst("id"));
    	System.out.println("-> firstName: " + customer.getFirst("firstName"));
    	System.out.println("-> lastName: " + customer.getFirst("lastName"));
    	System.out.println("-> location: " + customer.getFirst("location"));
    	
    	return new ResponseEntity<String>("", HttpStatus.OK);
    }

Para realizar una solicitud con form-urlencoded en Postman, puede usar la pestaña Body y seleccionar la opción x-www-form-urlencoded. Luego, ingrese el nombre y el valor de cada parámetro.

Conclusión

Como hemos visto en este artículo, configurar parámetros en Spring Rest API es un proceso relativamente sencillo. Mediante el uso de anotaciones como @RequestParam y @PathVariable, puede acceder fácilmente a los diferentes tipos de parámetros que se envían en la petición. Además, puede usar la anotación @RequestBody para deserializar el cuerpo de la solicitud y vincularlo a un parámetro de método. Todas estas herramientas combinadas facilitan la creación de API REST que son flexibles y pueden manejar una amplia variedad de parámetros.

Referencias

• Google JSON Style Guide

Te puede interesar