Es habitual que algunos de los parámetros de nuestros servicios sean opcionales para el cliente, lo que provocaría la llega de estos valores en null para nuestra API, lo que puede resultar un problema para algunos parámetros que son requeridos para el correcto funcionamiento del API y que al menos debemos de tener un valor por defecto en caso de no enviarse.

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Mediante la anotación @DefaultValue podemos establecer un valor por default a algunos de nuestros parámetros que son opcionales para el cliente, lo que evita que tengan un valor nulo al llegar al API. Esta característica es especialmente buena en casos en los que el API necesita que estos parámetros tengan algún valor a pesar que el cliente no lo envíe, pues dejarlos en null puede provocar el fallo del servicio.

Imaginemos el siguiente ejemplo, tenemos que construir un servicios de consulta de clientes que permita paginar los resultados, por lo que el servicio deberá proporcionar la página actual y el número de registros esperados por página. En este ejemplo, podríamos imagina que si los valores no se definen, entonces el API debería de retornar todo, pero esto puede provocar un problema de performance, por que hay muchísimos clientes y cada cliente tiene una serie de objetos asociados que deberán ser retornados también, provocando una gran carga sobre la base de datos, es por ello, que debemos asegurarnos de que si el API no recibe estos parámetros entonces deberemos establecer un valor por default. Veamos el siguiente ejemplo:

package api.services;

import java.util.*;
import javax.ws.rs.core.*;

@Path("customers")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class CustomersService {
	
	@GET
	public Response getCustomers(
			@DefaultValue("1") @QueryParam("currentPage") int currentPage, 
			@DefaultValue("10") @QueryParam("pageSize") int pageSize) {
		
		//Validate input
		if(currentPage < 1 || pageSize < 1) {
			return Response.ok("Invalid params").build();
		}
		
		//ccreate Dataset 
		List<String> customers = new ArrayList<>();
		for(int c = 1 ; c<=100 ; c++) {
			customers.add("Customer " + c);
		}
		
		//Calculate sublist range
		int startIndex = (currentPage-1) * pageSize;
		int endIndex = startIndex + pageSize;
		
		//No more results
		if(startIndex >=customers.size()) {
			return Response.ok(new Object[0]).build();
		}
		
		//Prevent ArrayIndexOutOfBoundsException
		if(endIndex > customers.size()) {
			endIndex = customers.size();
		}
		
		//Getting sublist of elements
		List<String> filters = customers.subList(startIndex, endIndex);
		
		return Response.ok(filters)
				.header("x-size", customers.size())
				.header("x-startIndex", startIndex)
				.header("x-endIndex", endIndex)
				.build();
	}	
}

Para este ejemplo hemos definido que si el cliente no envía la página actual (currentPage) le daremos el valor de 1 por default, y para el tamaño de la página (pageSize) hemos definido el valor de 10. Esto quiere decir que en caso de que el cliente no envíe estos parámetros, regresaremos los 10 primeros registros.

También hemos retornado los headers x-size, x-startIndex, x-endIndex como metadato para el cliente, para que sepa el total de los elementos, el index del primer registro y el último respectivamente.

Veamos algunos ejemplos. En primer lugar probaremos ejecutar el servicio sin ninguno de los parámetros, para comprobar los valores por default:

Podemos comprobar que se han retornado los primeros 10 resultados.

Hora probaremos únicamente con el parámetro pageSize=3, lo que establecerá la página por default en 1, regresando los primeros 3 resultados:

Conclusiones

Los valores por default son una excelente opción para lidiar con valores requeridos por el API, pero que nos obligatorios para el cliente, sin embargo, el echo de que tengamos valores por default, no significa que no debemos validar los parámetros, pues el cliente siempre podrá enviar valores no esperados por el API que provoquen una falla o en el peor de los casos, hacer una inyección SQL.

The post Valores por defecto con @DefaultValue appeared first on Oscar Blancarte - Software Architecture.

Los bean params hacen referencia a la capacidad de JAX-RS para recibir como parámetro objetos complejos definidos por una clase, esta clase puede ser vista como un Data Transfer Object (DTO), la cual contiene una serie de propiedades recuperadas de varias partes del request, como el header, query, path y formulario.

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Los Beans params no es una característica nativa del protocolo HTTP o la arquitectura REST, si no que JAX-RS la agrega para poder mapear todos los tipos de parámetros en una sola clase, la cual podríamos ver como un DTO que concentra en un solo punto todos los parámetros esperados.

Para comprender mejor como funcionan los Beans params, imaginemos que tenemos un formulario para registrar nuevos clientes, este formulario enviara al servicio todos los campos al API por medio de @FormParams, también enviaremos como un header un token de autenticación, para identificar al usuario que está realizando la invocación, imaginemos que el cliente llego por medio de una campaña promocional, por lo que necesitamos saber si llego por facebook, google, etc. por lo que enviaremos un @QueryParam para saber de donde llego el cliente.

Este caso, podríamos crear un parámetro en Java para uno de los parámetros esperados o podríamos crear una clase como la siguiente:

package api.services;

import javax.ws.rs.*;

public class CustomerDTO {
	@CookieParam("token") 
	private String token;

	@FormParam("firstname") 
	private String firstname; 
	
	@FormParam("lastname") 
	private String lastname;
	
	@FormParam("status") 
	private String status;
	
	@QueryParam("source")
	private String source;

	/* GET and SET */
}

La clase CustomerDTO es en realidad una composición de variables que son recuperadas de varias partes de la petición. Solo en este caso hemos recuperado parámetros de las cookies (@CookieParam), form (@FormParam), query (@QueryParam), sin embargo, la idea de los @BeanParam es que se pueden utilizar cualquiera de las @xxxParam, lo que quiere decir que podemos utilizar:

• @PathParam
• @QueryParam
• @MatrixParam
• @CookieParam
• @HeaderParam

El siguiente paso es crear un método REST que reciba el @BeanParam:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {
	
	@POST
	@Produces(MediaType.APPLICATION_JSON)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(@BeanParam CustomerDTO customer) {
		
		String result = String.format("firstname = %s, lastname = %s, status = %s, token = %s, source = %s", 
				new Object[]{customer.getFirstname(), 
						customer.getLastname(),
						customer.getStatus(), 
						customer.getToken(),
						customer.getSource()});
		
		return Response.ok(result).build();
	}	
}

El formulario con el que invocaremos el servicio REST es el siguiente:

<!DOCTYPE html>
<html>
	<body>
		<p>Customer form</p>
	
		<form action="http://localhost:8080/api-0.0.1-SNAPSHOT/customers?source=google" method="post">
			<div>
				<label for="firstname" style="display:inline-block; width: 100px;">Nombre</label>
				<input id="firstname" type="text" name="firstname" />
			</div>
			<div>
				<label for="lastname" style="display:inline-block; width: 100px;">Apellido</label>
				<input id="lastname" type="text" name="lastname" />
			</div>
			<div>
				<label for="status" style="display:inline-block; width: 100px;">Estatus</label>
				<select id="status" name="status" >
					<option value="active">Activo</option>
  					<option value="inactive">Inactivo</option>
				</select>
			</div>
			<br/>
			<input type="submit" value="Guardar" />
		</form>
	</body>
</html>

Observemos que hemos agregado el query param en el action del <form>, por lo que será enviado al servidor al momento del submit.

Adicional, agregaremos la cookie token directamente desde el inspector de chrome:

Y obtendremos el siguiente resultado:

Conclusiones

Como hemos podido validar, los @BeanParam son una excelente estrategia para realizar una composición de una serie de parámetros en una sola fuente de datos, los cuales podríamos fácilmente reutilizar para más de un servicio. Además, nos evita tener que definir una serie de parámetros para poder recuperar cada uno de los valores esperados.

The post Bean Params con @BeanParam appeared first on Oscar Blancarte - Software Architecture.

Las cookies son hasta la fecha una de las formas más utilizadas que tenemos para persistir valores del lado del cliente, las cuales pueden ser recuperadas por el servidor para identificar a un usuario, darle seguimiento o simplemente para guardar algún valor que utilizaremos después.

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Todas las cookies que guardemos en el cliente serán transmitidas al servidor de forma automática al servidor en los request posteriores, lo que puede ser de grán ayuda para identificar la sesión del usuario, el estado o incluso, guardar tokens de autenticación para identificar al usuario en cada llamada.

Las cookies no es algo que podamos ver a simple vista, pues solo se pueden ver con ayuda de herramientas que monitoren el tráfico HTTP, como es el caso del inspector de elementos de Chrome u otras herramientas especializadas como es el caso de Restlet, SOAPUI, postman, etc.

Desde chrome podemos ver todas las cookies que una página ha dejado en nuestro equipo, e incuso, podríamos agregar algunas manualmente para realizar algunas pruebas. Para verlas, solo basta abrir el inspector de elementos, dirigirse a la pestaña de Application y seleccionar la opción de cookies, tal como podemos ver en la siguiente imagen:

Recuperar las Cookies con JAX-RS

Mediante el API de JAX-RS es muy fácil de recuperar las cookies del lado del servidor, ya que solo es necesario anotar con @CookieParam alguno de los parámetros del método Java en la cual queremos inyectar el valor de una cookie. Veamos el siguiente ejemplo que espera una cookie de autenticación llamado token:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {

	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(
			@CookieParam("token") String token) {
		
		if("1234".equals(token)) {
			return Response.ok("OK").build();
		}else {
			return Response.ok("UNAUTHORIZED").status(Response.Status.UNAUTHORIZED).build();
		}
	}
}

En este ejemplo estamos el header token, el cual deberá tener el valor 1234, de lo contrario, mandaremos un error de autenticación.

Establecer una nueva Cookie

Otra cosa que podemos hacer es establecer una nueva cookie en el cliente, por ejemplo, podríamos agregar el token en caso de que este no tenga uno, veamos cómo quedaría:

package api.services;

import java.util.Map;
import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {

	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(
			@CookieParam("token") String token) {
		
		if(token == null) {
			NewCookie newToken = new NewCookie("token", "1234");
			return Response.ok("OK").cookie(newToken).build();
		}
		
		return Response.ok("OK").build();
	}	
}

Utilizamos la clase NewCookie para definir una nueva cookie que deberá ser creada en el cliente, demás, utilizamos el método cookie de la clase Response para enviarla al cliente.

Conclusiones

A pesar de que las cookies han sido la forma tradicional de guardar los datos en el cliente, la llegada de HTML5 nuevas alternativas, como lo es el Local Storage y el Session Storage, de los cuales no hablaremos en esta ocasión, pero las menciono por si quieres investigar un poco más al respecto.

The post Cookie params con @CookieParam appeared first on Oscar Blancarte - Software Architecture.

Los header son utilizados en REST para enviar metadatos asociados a la petición o la respuesta, los cuales van desde el formato y tamaño del payload, nombre del servidor del servidor de aplicaciones, fecha de invocación, caducidad de un recurso, versión y nombre del sistema operativo, tipo de navegador, dispositivo, lenguaje y hasta headers para la seguridad.

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Los headers es una sección adicional al payload de una solicitud, la cual no puede ser vista a simple vista, si no que requiere de un analizador HTTP para poderlos ver, sin embargo, todas las solicitudes llevan por default una serie de headers, incluso si nosotros no las establecemos. Los headers enviados por default varían de cliente a cliente y de servidor a servidor, por lo que en este artículo aprenderemos a analizar los headers.

Uno de los principales usos de los header es para enviar los tokens de
autenticación, como es el caso de JSON Web Token (JWT), el cual lo establecemos en el header Authorization, dicho lo anterior, veremos como recuperar este header mediante el API JAX-RS de Java.

package api.services;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("security")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class Security {
	
	@GET
	public Response authenticate(@HeaderParam("authorization") String token) {
		return Response.ok("token="+token).build();
	}
}

Los header pueden ser recuperados anotando los parámetros con @HaderParam, por lo que vamos a requerir un parámetro en Java por cada header que esperamos recibir en el API.

Si ejecutamos el ejemplo anterior, podemos ver el siguiente resultado:

En la parte superior podemos ver los header que definimos en el request y en la parte de abajo los header que nos retorno el servidor; en la respuesta podemos ver el token que le hemos enviado.

Otra de las formas de recuperar los header es por medio de la clase HttpHeaders, la cual podemos inyectar a nuestro método mediante la anotación @Context. La ventaja evidente de esté método es que podemos recuperar cualquier header, sin importar si lo esperábamos o no y nos evita tener que definir una grán cantidad de parámetros si esperamos muchos headers. Veamos un nuevo ejemplo con este método:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("security")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.TEXT_PLAIN)
public class Security {
	
	@GET
	public Response authenticate (@Context HttpHeaders headers) {
		String result = "";
		for(Map.Entry entry: headers.getRequestHeaders().entrySet() ) {
			result += entry.getKey() + "=" + entry.getValue() + ", ";
		}
		
		return Response.ok(result).build();
	}
}

Ahora veamos una ejecución de prueba:

En este caso, podemos observar que hemos recibido muchos más parámetros de los que enviamos, y esto se debe a lo que mencionamos al inicio, y es que cada cliente agrega una serie de headers para identificarlo.

Agregar headres en la respuesta

Ademas de recibir headers, también podemos enviar headers a los clientes del API; los headers los podemos agregar directamente al objeto Response, mediante una serie de claves-valor, veamos un ejemplo:

package api.services;

import java.util.Map;
import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("security")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.TEXT_PLAIN)
public class Security {
		
	@GET
	public Response authenticate (@Context HttpHeaders headers) {
		String result = "";
		for(Map.Entry entry: headers.getRequestHeaders().entrySet() ) {
			result += entry.getKey() + "=" + entry.getValue() + ", ";
		}
		
		Response.ResponseBuilder response = Response.ok(result);
		response.header("my-header1", "value 1");
		response.header("my-header2", "value 2");
		
		return response.build();
	}
}

Conclusiones

No debemos de confundirnos al momento de utilizar los headers, pues no se deben de utilizar como una forma de enviar parámetros a nuestro API, si no como metadatos que complementen el request y que ayuden al servidor/cliente como tratar la solocitud/respuesta.

The post Header params con @HeaderParam appeared first on Oscar Blancarte - Software Architecture.

Una de las cosas que pocos saben, es que REST nos permite crear servicios que se integren a la perfección con los formularios HTML, de tal forma que podemos lugar una etiqueta <form> directamente con un servicio REST. para ello, JAX-RS nos proporciona la anotación @FormParam.

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

La diferencia fundamental que tienen los form params con respecto a los demás, es que se obtiene directamente los campo asociados al formulario desde el cual se ejecuta, pero para entender mejor, veamos el siguiente ejemplo:

<html>
	<body>
		<p>Customer form</p>
		<form action="http://localhost:8080/api-0.0.1-SNAPSHOT/customers" method="post">
			<div>
				<label for="firstname" style="display:inline-block; width: 100px;">Nombre</label>
				<input id="firstname" type="text" name="firstname" />
			</div>
			<div>
				<label for="lastname" style="display:inline-block; width: 100px;">Apellido</label>
				<input id="lastname" type="text" name="lastname" />
			</div>
			<div>
				<label for="status" style="display:inline-block; width: 100px;">Estatus</label>
				<select id="status" name="status" >
					<option value="active">Activo</option>
  					<option value="inactive">Inactivo</option>
				</select>
			</div>
			<br/>
			<input type="submit" value="Guardar" />
		</form>
	</body>
</html>

En este ejemplo debemos poner atención en la etiqueta <form>, la cual está apuntando a un servicios REST mediante la etiqueta action, con lo cual le estamos diciendo al navegador que envíe el formulario a nuestro servicio REST.

Otra de las cosas a tomar en cuenta son los campos dentro del form, como lo son el nombre, apellido y estatus, los cuales serán los que sean enviados al servicio REST.

Una vez explicado lo anterior, pasemos a la implementación en JAX-RS para recuperar estos parámetros:

package api.services;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {

	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response saveCustomer(
			@FormParam("firstname") String firstname, 
			@FormParam("lastname") String lastname, 
			@FormParam("status") String status) {
		
		String result = String.format("firstname = %s, lastname = %s, status = %s", new String[]{firstname, lastname, status});
		return Response.ok(result).build();
	}
}

Veamos como hemos definido una anotación @FormParam para cada uno de los parámetros esperados del formulario, los cuales serán mapeados a cada uno de los parámetros del método en Java.

Las anotaciones @Consumes la utilizamos definir que esperamos el payload como un formulario.

Probando el servicio

Lo primero será abrir el la página HTML para verlo de la siguiente manera:

Una vez capturado el formulario, la damos grabar, lo que detonará el submit del formulario y la ejecución del servicio REST, lo que dará como resultado lo siguiente:

Podemos ver como el servicio REST ha recibido todos los parámetros y los ha regresado como una cadena de texto.

Mediante la anotación @FormParam es fácil recuperar los valores de un formulario, pues los mapeamos a una parámetro especifico del método Java, sin embargo, esta forma tiene la limitación de que requerimos N parámetros en Java para mapear los N form params, lo que puede llegar a ser complicado en formularios grandes o donde los nombres de los parámetros pudieran variar, en tales casos, podemos implementarlos de la siguiente manera para recuperar todos los form params como un colección:

package api.services;

import java.util.Map;

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("customers")
public class CustomersService {
	
	@POST
	@Produces(MediaType.TEXT_PLAIN)
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	public Response getFormDataUsingMultivaluedMap(MultivaluedMap<String, String> formParams) {
		String result = "";
		for(Map.Entry entry: formParams.entrySet() ) {
			result += entry.getKey() + "=" + entry.getValue() + ", ";
		}
		
		return Response.ok(result).build();
	}
}

Conclusiones

Los @FormParam pueden ser una buena alternativa cuando queremos ligar directamente un formulario con servicios REST, evitando tener que construir un request especifico.

Como inconveniente, tenemos que el servicio REST deberá retornar la estructura HTML de la siguiente página que verá el usuario, o en su defecto, podemos redireccionar al usuario a la siguiente página.

The post Path params con @FormParam appeared first on Oscar Blancarte - Software Architecture.

Otra de las formas que tenemos para enviar parámetros al API REST son los Query Params, los cuales son una serie de clave-valor que se agregan al final de la URL, justo después del signo de interrogación (?).

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Para comprender mejor que es un Query param a analizar la siguiente URL para consultar los clientes por medio del nombre:

http://myapi.com/customers?name=oscar

El query param es la clave valor name=oscar que vemos al final de la URL, y como regla, siempre deberán estar después del símbolo de interrogación. Además, una URL puede tener N query params, cómo el siguiente ejemplo:

http://myapi.com/customers?firstname=oscar&lastname=blancarte&status=active

Esta URL la podemos utilizar para buscar a todos los clientes donde su nombre es oscar, su apellido es blancarte y su estatus es activo. Cuando utilizamos más de un Query param, es importante separar cada uno mediante el simbolo &.

Recuperar los Query params con JAX-RS

Una vez explicado lo anterior, vamos a pasar a explicar como podemos recuperar los query params mediante el API JAX-RS de Java.

La forma más simple de recuperar un Query param es anotar los parámetros de los métodos con @QueryParam, de tal forma que deberemos tener un parámetro por cada query param esperado. Veamos el siguiente ejemplo:

@GET
@Path("customers")
public Response getCustomers(
		@QueryParam("firstname") String firstname, 
		@QueryParam("lastname") String lastname, 
		@QueryParam("status") String status) {
	String result = String.format("firstname = %s, lastname = %s, status = %s", new String[]{firstname, lastname, status});
	return Response.ok(result).build();
}

Podemos observar que hemos definido la anotación @QueryParam en cada parámetro sobre el cual queremos mapear el parámetro.

Veamos ahora un ejemplo del ejecución de este método:

Como resultado podemos ver que hemos recibido los parámetros desde Java y devueltos como parte de la respuesta, lo que demuestra que hemos logrado mapear los query params con los parámetros del método Java.

El ejemplo anterior es la forma más simple de recuperar los query params, sin embargo, tiene el inconveniente de que debemos definir un parámetro en Java para cada query param que esperamos recibir, lo que puede ser complicado si tenemos muchos o los nombre de los query params pueden variar, pues no tendremos forma de predecirlos para mapearlos a un parámetro en Java.

Para solucionar estos casos tenemos la clase UriInfo, la cual debemos de inyectar al método en lugar de los @QueryParam, veamos el siguiente ejemplo:

@GET
@Path("customers2")
public Response getCustomers(
		@Context UriInfo uriInfo) {
	String result = "";
	for(Map.Entry entry: uriInfo.getQueryParameters().entrySet() ) {
		result += entry.getKey() + "=" + entry.getValue() + ", ";
	}
	return Response.ok(result).build();
}

En este nuevo ejemplo podemos apreciar que hemos inyectado la clase UriInfo mediante la anotación @Context y por medio de esta clase podemos recuperar todos los query params, sin importar la cantidad que nos envíen e incluso si lo esperamos o no. La ventaja de este método es que podemos recuperar todos los query params como un Set e iterar todos los query params enviados.

Observemos en esta última prueba que hemos enviado los query params de siempre y hemos agregado el param date.

Conclusiones

Hemos comprobado lo fácil que es recuperar los query params con @QueryParam, he incluso, recuperarlos mediante la clase UriInfo, pero hay que tener cuidado al momento de utilizarlos, pues en muchos de los casos, podríamos pasar los parámetros mediante @PathParam.

Por lo general, los @QueryParam se utilizan para complementar las búsquedas y los @PathParam para establecer el contexto de la búsqueda, es decir, mediante @PathParam decimos lo que estamos buscando y los @QueryParam como los queremos o los filtros de la selección.

The post Query params con @QueryParam appeared first on Oscar Blancarte - Software Architecture.

API REST no es una moda y llego para quedarse, solo basta ver las tendencias de Google Trends para darnos cuenta que REST ha superado por creces a los servicios tradicionales SOAP y desde hace ya un tiempo. API REST ha tenido un enorme éxito debido a tecnologías tan populares como JavaScript y IoT, las cuales tienes un comunicación casi nativa y con bajos consumos.

The post Qué es API REST? – 🚀Y por que es importante aprenderlo 🚀[VIDEO] appeared first on Oscar Blancarte - Software Architecture.

URL Paths

Uno de los aspectos más importantes de un servicio REST, es su URL, primero que nada, porque es la forma en que podemos consumir el servicio, pero también es importante por le da al usuario una pista significativa acerca de su funcionalidad. Una URL bien definida, podría decirle al usuario para que sirve con una precisión muy acertada, sin tener que recurrir a la documentación.

Para que una URL tenga un significado real, es necesario complementarlo con método (o verb) al que responde, pues el método nos dice el tipo de operación que va a realizar, mientras que la URL nos dice que es lo que va hacer. Analicemos las siguientes URL:

Quiero que te tomes solo un momento para analizar las URL anteriores… te aseguro que sin ser un experto pudiste adivinar con gran certeza que hace cada una de estas operaciones. Si no, te recomiendo ver la segunda parte de este artículo para refrescar un poco la memoria.

Como sea, vamos a explicar que hace cada una, en la primera URL, sabemos que el GET se utiliza para consultas y la URL habla de usuarios, luego un nombre y finalmente un avatar, por lo que podemos deducir que este servicio está realizando la consulta del Avatar del usuario oscar, ¿vez que fácil?

En la segunda URL, sabemos que PUT se utiliza para realizar updates, por lo tanto, le estamos diciendo que actualice el Avatar del usuario oscar.

En la tercera URL, sabemos que DELETE se utiliza para borrar un registro, por lo que está de más decir que lo que hace es borrar el usuario oscar.

En la cuarta URL, sabemos que POST se utiliza para crear un nuevo registro y está invocando solamente /users, esto me dice que el servicio está creando un nuevo usuario.

Con Express es realmente fácil implementar estas URL, tan solo hay que definir los Routers con el método adecuado y con el URL al que debe procesar, veamos cómo quedaría:

app.get('/users/oscar/avatar', (req, res) => {
  res.send('Hello GET:/users/oscar/avatar')
})

app.put('/users/oscar/avatar', (req, res) => {
  res.send('Hello PUT:/users/oscar/avatar')
})

app.delete('/users/oscar', (req, res) => {
  res.send('Hello DELETE:/users/oscar')
})

app.post('/users', (req, res) => {
  res.send('Hello POST:/users')
})

Los paths siempre deben de representar exactamente lo que hacen, y el método debe de corresponder con la acción que realizará, pues no hacerlo, puede confundir a los desarrolladores.

Prioridad de los paths

Un error al momento de iniciar con Express es pensar que el orden en que se definen los Routers es irrelevante, como si de una función se tratara, la cual puede ser llamada desde donde sea y siempre se ejecuta la correcta, sin embargo, esto no es cierto. Por este motivo, Express evaluar los Router en el orden en que están definidos.

Existe ocasiones en que más de una URL puede colisionar y entrar en el Path equivocado, por ejemplo, las siguientes dos URL:

GET: /*

GET:/login

La primera acepta cualquier URL, porque tiene un comodín (*), mientras que la segunda, solo acepta la URL /login. En este caso, como /* esta primero, entonces atenderá las peticiones que lleguen a /login, porque el path /* cumple con el patrón, en tal caso, tendríamos que invertir el orden de los Routers de la siguiente manera:

GET:/login

GET: /*

De esta forma, cuando llegue una petición a /login, la tomará el primer Router y para todos los demás path será /* quien procese la solicitud.

URL Params

Una de las características de REST, es la posibilidad de convertir ciertas partes de una URL en parámetro, de tal forma que nos ahorra tener que escribir una URL para cada registro que necesitemos.

Regresando al ejemplo de los servicios para usuarios GET: /users/oscar, podemos apreciar que “oscar” esta fija en la URL, lo que provocaría que tuviéramos que tener un Router para cada usuario registrado. Por suerte, Express nos permite escribir URL Params. Para convertir una sección de la URL en URL param, solo tendremos que anteponer dos puntos (:) antes, por ejemplo:

/users/:username

/users/:username/:field

En la primera URL podríamos recibir consultas para todos los usuarios, por ejemplo:

/users/oscar , /users/juan , /users/pedro

Mientras que en la segunda URL podríamos consultar cualquier campo del usuario, por ejemplo:

/users/oscar/avatar  o /users/juan/banner

Para recuperar los URL Params, tan solo es necesario recuperarlos del objeto request de la siguiente manera: req.params.<name>. Veamos algunos ejemplos:

Query params

Los query params son lo más conocidas, y son todos aquellos que van al final de la URL seguido del símbolo de interrogación (?). Se pueden enviar cuantos Query params se requiere, siempre y cuando no excedamos el límite máximo de caracteres para un URL. Cada parámetro deberá está separado un el símbolo de ampersand (&). Algunos ejemplos:

/cources?coupon=FREE&Source=Google

Este tipo de parámetros es muy común en campañas publicitarias, pues el param coupon determina que el curso a comprar es gratis (free), mientras que el param Source nos dice de donde llego el cliente (google).

Para recuperar un Query param en Express se usa la siguiente sentencia, req.query.<parama-name>. Veamos cómo implementarlo en Express.

app.get('/cources', (req, res) => {
  var coupon = req.query.coupon
  var source = req.query.source
  res.send("Coupo: " + coupon + ", Source: " + source)
})

Si ejecutamos la URL /cources?coupon=FREE&Source=Google  obtendremos el siguiente resultado:

Body params

El tercer y último tipo de parámetro que podemos enviarle a un servicio REST, es el payload (o body), el cual puede ser un mensaje largo que no se puede ver a simple vista. No todos los métodos HTTP soportan el envío de un payload, por lo que hay que tener eso en cuenta.

De los métodos más utilizados que soportan el envío de un payload son: POST, PUT, PATCH, DELETE. Observa que el método GET no lo soporta.

Recuperar el body del request no está simple como parecería, pues en realidad, este parámetro es un InputStream, lo que quiere decir, que se recibe como los datos poco a poco y no todo de una. Esto nos obliga a procesar el payload a medida que va llegando. Este proceso lo podemos simplificar con ayuda del módulo body-parser, el cual instalamos en la primera parte de este artículo (npm install –save body-parser).

Mediante este módulo, es posible convertir el payload en varios formatos, pero el que nos interesa es JSON, pues es el estándar para REST. Configurarlo, solo tendremos que importarlo y agregar un middleware (los analizaremos más adelante).

Finalmente, existe una última forma de recibir información para el API, la cual es a través de Header, sin embargo, esta parte la dejaremos para la siguiente parte, en la cual hablaremos de la autenticación mediante JSON Web Tokens (JWT).

The post Construir un API REST con NodeJS (Tercera parte) appeared first on Oscar Blancarte - Software Architecture.

También puedes ver como implementar los verbs con Java en mi guía de implementación de un API REST con Java.

Verbs

Uno de los conceptos más importantes cuando trabajamos con REST, son los Verbs (o también llamados métodos), los cuales conocemos como GET, POST, DELETE, PATCH, PULL, etc. determinan la acción que deseamos hacer sobre un determinado recurso. En REST, cada método tiene un significado para el API, pues una misma URL puede tener diferente significado dependiendo sobre el método se ejecutó.

Por ejemplo, la URL /user/oscar sobre el método GET, representa una consulta para el API, mientras que la misma URL sobre el método DELETE, representa una instrucción de borrar al usuario.

Los métodos (o verbs) más utilizados en un API REST son:

• GET: Se utiliza para realiza consultas (Select)
• POST: Se utiliza para crear nuevos registros (Insert)
• DELETE: Se utiliza para borrar un registro (Delete)
• PUT: Se utiliza para actualizar total o parcialmente un registro existente (Update)
• PATCH: Se utiliza para actualiza solo una pequeña parte de un registro existente (Update)

Puedes ver la lista completa de método soportados en la siguiente en la documentación oficial de Express.

Utilizando los verbs con Express

En express es realmente fácil crear servicio que atienda peticiones en los diferentes métodos, ya que proporciona una función para cada uno de ellos, el cual se define de la siguiente manera:

express.<verb>(<path>, <callback>)

El <verb> representa el método HTTP soportado por express en minúscula, el <path> es la ruta en la cual escucha las peticiones y el <callback> es la función que procesará las peticiones, la cual recibe dos parámetros, el primero es un objeto que representa el request y el segundo es el objeto que representa la respuesta, por ejemplo:

var express = require('express')
var http = require('http')
var app = express()

var users = ['oscar', 'juan', 'marcos']

app.get('/users', (req, res) => {
  res.send(users)
})

app.get('/', (req, res) => {
  res.status(200).send("Welcome to API REST")
})

http.createServer(app).listen(8001, () => {
  console.log('Server started at http://localhost:8001');
});

Veamos las líneas 5 y 9, hemos definido dos Routers, los cuales atienden peticiones GET, sin embargo, las dos atienden en diferente path, por lo que si ejecutamos la URL http://localhost:8001/users tendremos un resultado diferente que ejecutar simplemente http://localhost:8001.

Al igual que tenemos Router para procesar peticiones GET, podemos agregar otros métodos, como, por ejemplo:

app.post('/users', (req, res) => {
  users.push('User ' + users.length)
  res.send("New user add")
})

Este nuevo Router atiende peticiones POST en el path /users, y tiene como funcionalidad agregar un nuevo usuario a la lista actual de usuario y retorna un mensaje al cliente. Desde luego que este servicio no lo podemos probar desde el navegador, por lo que utilizaremos el plugin Restlet de Chrome para probarlo, el resultado es el siguiente:

De esta forma, podemos agregar tantos métodos necesitemos para nuestra API, por ejemplo:

app.patch('/users',(req, res) => {
  res.send('PATCH method')
})

app.delete('/users',(req, res) => {
  res.send('DELETE method')
})

Como hemos visto hasta ahora, es posible definir una serie de Router capaces de atender en los diferentes métodos que ofrece Express, también hemos visto que es posible definir más de un Router con el mismo método para atender diferentes URL.

En la siguiente parte de este artículo hablaremos acerca de los paths y como parametrizarlos para atender en URL dinámicas.

Continuación (Tercera parte)

The post Construir un API REST con NodeJS (Segunda parte) appeared first on Oscar Blancarte - Software Architecture.

Si no sabes muy bien que es un API REST, te invito a que veas mi video un Youtube donde lo explico “Qué es API REST? – 🚀Y por que es importante aprenderlo 🚀”

Construir un API REST es realmente simple, y más aún, si cuentas con las tecnologías adecuadas. En este sentido, NodeJS + Express, se ha convertido en la combinación perfecta para realizar esta tarea, pues es posible construir y levantar un API REST en cuestión de segundos.

Preparando el proyecto

Lo primero será crear un nuevo proyecto desde el cual estaremos trabajando, para ello, crearemos una nueva carpeta en cualquier parte y nos ubicaremos en ella a por medio de la línea de comandos. Una vez allí, ejecutaremos el comando npm init , el cual nos solicitará algunos datos referentes al proyecto, al finalizar, nos habrá creado el archivo package.json y una carpeta llamada node_modules, la cual contiene todas las librerías estándar de NodeJS.

En este punto, tendremos que instalar los módulos de NPM que vamos a requerir, para ello, ejecutaremos los comandos:

• npm install –save express
• npm install –save body-parser

Express es el módulo más popular para desarrollos web en NodeJS y además, es especialmente útil para la construcción de API’s, por otra parte, el Middleware body-parse, que anteriormente era parte de Express, nos ayudará a procesar el payload (o body) del request, el cual nos lo dejar listo y en el formato que lo necesitamos, en este caso, en JSON.

En este punto, tendremos un archivo package.json  muy parecido al siguiente:

{
  "name": "api-rest",
  "version": "1.0.0",
  "description": "Mi primer API REST",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "API",
    "REST",
    "NodeJS"
  ],
  "author": "Oscar Blancarte",
  "license": "ISC",
  "dependencies": {
    "body-parser": "^1.18.2",
    "express": "^4.16.2"
  }
}

Levantando un servidor

El siguiente paso será montar un servidor usando NodeJS + Express, para lo cual, tendremos que crear un nuevo archivo llamado server.js  directamente sobre la raíz del proyecto, el cual se verá de la siguiente manera:

var express = require('express')
var http = require('http')
var app = express()

app.get('/', (req, res) => {
  res.status(200).send("Welcome to API REST")
})

http.createServer(app).listen(8001, () => {
  console.log('Server started at http://localhost:8001');
});

Con estas simples líneas, hemos creado un servidor web capaz de servir peticiones web, sobre el cual montaremos nuestra API REST. Antes de ejecutar este código, vamos a analizar qué está pasando. Lo primero que podemos apreciar, es que importamos el módulo Express del que ya hablamos y el módulo Http, el cual es parte del estándar NodeJS, por lo que hace falta instalarlo con NPM. Este segundo módulo es utiliza para crear oyentes capases de escuchar peticiones HTTP en un determinado puerto. El segundo paso será crear una instancia de Express, como podemos observar en la línea 3.

Una vez hechos con la instancia de Express, solo nos resta crear los Routers, los cuales son las reglas por medio de las cuales Express sabrá como procesar las diferentes peticiones en diferentes URL’s, para lo cual, Express proporcionar una serie de funciones para procesar los diferentes métodos que soporta HTTP, como es GET, POST, DELETE, PUT, etc. En este caso, hemos creado un router para atender las peticiones que lleguen a la raíz del servidor. Es por eso la importancia de la línea 5, la cual responderá con la frase “Welcome to API REST” al recibir una petición GET a la raíz del servidor.

Al igual que tenemos la función GET, tenemos todas las demás, por ejemplo, POST, DELETE, PUSH, PUT, etc. las cuales se definen de la misma forma que GET, pero solo es necesario cambiar la función con la del método HTTP deseado, por ejemplo: app.post(), app.delete(), app.push(), app.put(). Todas estas variantes, reciben dos parámetros, el primero es la URL en la cual responden y el segundo es una función (Callback) la cual será ejecutada una vez que una petición sea recibida.

Finalmente, y una vez que tenemos todas las reglas de routeo (routers), tendremos que crear un oyente para recibir las peticiones, para ello nos apoyamos del módulo Http como podemos ver en la línea 9. El server Http lo creamos (createServer) pasando como parámetro la instancia de Express para finalmente levantar el servidor con la función listener. Esta última, recibe el puerto en el que escucha y una callback que se ejecuta una vez levantado el server.

Probando el servidor

Una vez que tenemos una primera versión de nuestro servidor, solo nos queda probarla para asegurarnos de que todo funciona bien, por lo cual, regresamos la línea de comandos y ejecutamos node server.js , como resultado tendremos lo siguiente:

Una vez tenemos la confirmación de que nuestro server esta arriba, procedemos con probarlo con el navegador, por lo que entramos a la URL http://localhost:8001 y veremos el siguiente resultado:

Si ves esto, es porque nuestro servidor ya está listo. No es gran cosa, pero al menos ya es avance para construir nuestra API REST.

Ya con esto, tenemos todo preparado para iniciar con la construcción de nuestros servicios, pero esto lo dejaremos para la segunda parte de este artículo.

Continuación (Segunda parte)

The post Como construir un API REST con NodeJS (Primera parte) appeared first on Oscar Blancarte - Software Architecture.