¡Esta es una revisión vieja del documento!
Hay libros enteros que hablan sobre REST así que en esta unidad solo vamos a ver lo principal de REST sin entrar en detalle finos. Aun así, lo que vamos a ver creo que es suficiente para gran cantidad de aplicaciones por lo que no debemos pensar que nos quedaremos cortos.
Para saber hasta donde vamos a ver de REST podemos usar el modelo de madurez creado por Leonard Richardson y explicado por Martin Fowler en Richardson Maturity Model. Este modelo explica que hay 4 niveles de madurez para usar REST que son 1):
Aquí vamos a explicar los niveles 1 y 2 2).
Podríamos decir que REST es usar toda la potencia de HTTP en nuestras propias aplicaciones. Así que es necesario saber algo de HTTP para poder explicar REST.
HTTP como casi todo en informática lo podemos ver como una caja a la que le enviamos datos y nos retorna datos. Lo importante de HTTP es saber que tipos de datos se envían y que tipos de datos se responden. A primera vista podemos pensar que lo que se envía es una URL y lo que se retornan son los datos. Pero también hay que tener en cuenta los códigos de estado en la respuesta como por ejemplo el 404 “No encontrado”. Otra dato es si enviamos por POST o GET, etc.
Por ello vamos a describir los datos que enviamos y recibimos por HTTP 3).
Los datos que se envían es una petición HTTP son:
Los datos que se reciben en una petición HTTP son:
REST es una arquitectura para aplicaciones en red similar a SOAP o XML-RPC pero se diferencia de ellos en su sencillez y que utiliza todas las características que puede de de HTTP en vez de reinventarse lo que ya tiene HTTP.
Esta última característica yo creo que es la que mejor explica que es REST: Si algo ya existe en HTTP y REST siempre funciona bajo HTTP, ¿porque no usar entonces todo lo que ofrece HTTP?. Por lo tanto cuando necesitemos algo en nuestra aplicación siempre debemos preguntarnos , ¿como resuelve este problema ya el protocolo HTTP? Y usarlo en vez de crear nuestra solución.
Hablando de una forma sencillo lo que nos dice es como debemos comunicarnos desde la página web 4) con el servidor especificando cosas como:
Sabemos que HTTP tiene operaciones como GET y POST, pero tiene algunas mas que vamos a explicar ahora mismo 5).
Vamos a ver 4 método HTTP que coinciden con los 4 métodos de un CRUD o con operaciones de SQL
Método HTTP | Descripción | Metodo CRUD | Metodo SQL |
---|---|---|---|
GET | Este método HTTP lo usaremos para cuando queremos leer datos del servidor | Read | SELECT |
POST | Este método HTTP lo usaremos para añadir datos al servidor | Crear | INSERT |
PUT | Este método HTTP lo usaremos para actualizar 6) datos del servidor | Update | UPDATE |
DELETE | Este método HTTP lo usaremos para borrar datos del servidor | Delete | DELETE |
Así por ejemplo, para borrar un seguro médico del servidor ya no usaremos un GET con una url del estilo http://miapp.com/seguros/borrar/seguromedico sino que es obligatorio que el método sea DELETE. Y lo mismo con el resto de métodos.
Ya tenemos las operaciones, ahora pasemos al formato de la URI. La URI es como la URL pero le hemos quitado la parte inicial de la URL ya que la parte inicial depende de donde instalemos la aplicación.
Vamos a ver las características que deben tener las URI
/api/seguromedico/delete
, para indicar la acción ya está el método HTTP. Es decir no puede hacer verbos en la URI como borrar, copiar , imprimir, cerrar, etc.Accept
. Esta cabecera indica el formato que queremos que nos envíe el servidor. Por ejemplo si incluimos la cabecera Accept: application/json
significará que lo queremos en formato JSON./api/seguromedico?idSeguro=34
sino que lo correcto es /api/seguromedico/34
. /api/banco/4567/sucursal/67
. Es decir queremos la sucursal 67 pero del banco 4567./api/seguromedico/?nombre=Juan&ape1=Cano
Con todas estas reglas vamos a ver las URI que se suelen usar en una aplicación. Vamos a usar como ejemplo la entidad “Usuario”, es decir la URI que usaríamos para hacer un CRUD de la Tabla o Entidad “Usuario”.
Descripción | URL | Método HTTP | JSON Enviado | JSON Retornado |
---|---|---|---|---|
Leer un usuario | /api/Usuario/{idUsuario} | GET | Ninguno | Usuario leido |
Buscar usuarios | /api/Usuario/?columnaBusqueda1=valor1&columnaBusqueda2=valor2&…. | GET | Ninguno | Array de usuarios |
Añadir un usuario | /api/Usuario | POST | Usuario a insertar | Usuario insertado |
Actualizar un usuario | /api/Usuario/{idUsuario} | PUT | Usuario a actualizar | Usuario actualizado |
Borrar un usuario | /api/Usuario/{idUsuario} | DELETE | Ninguno | Ninguno |
Donde pone {idUsuario}
se subtituiría por el id del usuario.
El “JSON Enviado” es el JSON que se debe enviar con los datos al hacer esa petición. Como podemos ver solo se envía al insertar o al actualizar. Es decir es el JSON del usuario a insertar o el JSON con los nuevo datos del usuario a modificar.
El “JSON Retornado” es lo que nos retornará el servidor. Como vemos nos retorna un JSON con los datos en todos los casos excepto en el borrado, y no lo hace ya que no existe ningún dato a retornar ya que lo hemos borrado. Son realmente el JSON que esperamos con los datos de los usuarios al hacer la petición.
Puede parecer extraño que en el insert y el update se retornen los datos en formato JSON con el usuario recién insertado o actualizado. Esto lo hago ya que al insertar o actualizar puede que el servidor haya modificado los datos. Un clásico ejemplo es poner la fecha de creación/modificacion o poner el id de la clave primaria. Por ello lo retornamos para que el cliente tenga toda la información.
Una posible modificación que vi en un proyecto real consistía en hacer que el update y el insert no retornaran el objeto completo actualizado o insertado. Y no lo retornaban para ahorra tiempo y ancho de banda. Solo se retornaba en id del objeto recién insertado. Luego si hacía falta todos los datos , cosa que no solía necesitarse, se podían obtener con una llamada a GET
extra.
Como ya podemos imaginar la gestión de errores la tenemos que hacer siguiendo los códigos de estado de HTTP.
En la siguiente imagen podemos ver los códigos que usa Yahoo en su API de social:
Controlar todos estos códigos en la aplicación es un poco excesivo, así que nosotros vamos a simplificar el números de códigos que retornará nuestra aplicación.
Primero empecemos solo con 3 códigos: