Table of Contents

Diseño de APIs: Protocolo HTTP

Mensajes HTTP

En el protocolo HTTP existen 2 tipos de mensajes:

Petición HTTP

Toda petición HTTP está compuesta de:

Figure 1: Estructura petición HTTP (fuente: https://mozilla.org)

Respuesta HTTP

Toda petición HTTP conlleva una respuesta, ya sea por haberse ejecutado ésta correctamente o bien para informar de un error. Estará compuesta de:

Figure 2: Estructura respuesta HTTP (fuente: https://mozilla.org)

Métodos HTTP

El protocolo HTTP define una serie de métodos que permiten indicar el tipo de operación que se quiere realizar en toda petición HTTP.

La fundación Mozilla mantiene una documentación muy buena sobre todos los métodos que existen en el protocolo.

Documentación métodos HTTP en mozilla.org

Como durante el curso no veremos todos ellos, dejaremos en esta Wiki un resumen de lo más importante acerca de los métodos con los que vamos a trabajar.

Métodos HTTP más utilizados

En el protoclo HTTP, el método define el tipo de operación que se va a realizar. De entre los métodos existentes en el protocolo, los más utilizados son los que se corresponden con las operaciones CRUD:

Método Cuándo usar Ejemplo
GET Operación de consulta GET /books
POST Operación de registro o acciones POST /books ó POST /loan/12/cancel
DELETE Operación de borrado DELETE /book/12
PUT Operación de modificación completa PUT /book/12
PATCH Operación de modificación parcial PATCH /book/12

Cabe destacar el uso del método POST para todas aquellas operaciones que no se pueden clasificar como una operación CRUD de alta, baja, modificación o consulta de recurso. Por ejemplo, cancelar un préstamo, devolver un pedido, desactivar una tarjeta de crédito, . . .

Modelado de Recursos/URIs

Las URIs de cada recurso serán cada uno de los métodos que desarrollamos en el proyecto de nuestra API y mapeamos usando las anotaciones @GetMapping, @PostMapping, @DeleteMapping, @PatchMapping o @PutMapping.

Con el objetivo de definir una colección uniforme de operaciones o endpoints, es muy importante perder algo de tiempo para pensar y diseñar cómo deben de ser estas URLs.

El primer paso es tener en cuenta que el método HTTP seleccionado actuará como verbo y que la URL deberá definir al recurso sobre el que ese 'verbo' actúa (luego veremos que no todas las operaciones encajan en este modelo).

A continuación se muestran algunas URLs a modo de ejemplo:

Operaciones de consulta

Operaciones de registro

Operaciones de borrado

Operaciones de modificación (registro completo)

Operaciones de modificación parcial

Por ejemplo:

Figure 3: Rutas para operaciones en una API

Códigos de estado

El protocolo HTTP define una serie de códigos de estado que permiten indicar el resultado de toda petición HTTP. Estos códigos proporcionan al cliente que realizó la petición información global sobre el resultado que se devuelve en la respuesta.

La fundación Mozilla mantiene una documentación muy buena sobre todos estos códigos de estado.

Códigos de estado HTTP

Como durante el curso no veremos todos ellos, dejaremos en esta Wiki un resumen de lo más importante acerca de los códigos de estado con los que vamos a trabajar.

Existen 5 categorias:

Códigos de estado HTTP más utilizados

Código Estado Cuándo usar
200 OK Ok en GET,PUT,PATCH
201 Created Ok en POST (registro)
204 Not Content Ok sin devolver datos (normalmente en DELETE)
400 Bad Request Error de invocación del cliente
401 Unauthorized Usuario/Contraseña incorrectos
403 Forbidden Sin privilegios
404 Not Found Recurso no encontrado (especificado en la entrada)
500 Internal Server Error Error en backend

Ejercicios

  1. ¿Qué código de estado HTTP devolverá una operación que devuelve la lista de usuarios conectados cuando no haya ninguno? ¿Y qué información devolverá en la respuesta?
  2. ¿Qué código de estado HTTP debe devolver una operación que registra un nuevo producto en la base de datos? ¿Debe devolver algo como respuesta?
  3. ¿Qué código de estado HTTP y respuesta devolverá una operación que utiliza el método HTTP DELETE?
  4. ¿Qué código de respuesta HTTP devolverá una operación que sirve para conocer la información de un producto determinado? ¿Y si no lo encuentra?

© 2022-2024 Santiago Faci