El diseño de un API REST siempre es complejo y siempre surgen muchas muchas dudas . Esto es debido a que no siempre hay una única solución a una casuística determinada y se pueden aplicar varios enfoques . Vamos a hablar de un ejemplo sencillo que nos ayude a entender el concepto de homogeneidad y como esta nos pueda ayudar en nuestro día a día.
Normalmente cuando disponemos de un Servicio REST una de las operaciones más habituales es realizar una petición POST al servidor para insertar un recurso . Podríamos por ejemplo enviar una Factura vía JSON e insertarla a través del uso del verbo POST.
API REST y opciones
¿Ahora bien qué es lo que devolvemos una vez la inserción se ha realizado?. Existen varias opciones y todas ellas son posibles.
- No devolver nada excepto un codigo 201 de que el recurso se ha creado correctamente.
- Devolver la entidad en formato JSON de tal forma que podamos usarla en posteriores operaciones
- Devolver un link como cuerpo del mensaje que nos ligue a la url del nuevo recurso.
- Devolver en la cabecera un location header con un link al nuevo recurso
Todas las opciones son posibles
Es cierto que probablemente la cuarta opción es la que más ligada esta a lo que la especificación indica . Lo mejor es devolver un link en un location header. Sin embargo yo me he encontrado en situaciones en las que esta información pasa completamente desapercibida para el usuario del API ya que no dispone de los conocimientos para suponer que le devolvemos la entidad en el header.
¿Es entonces mejor devolver la propia entidad como parte de la respuesta en formato JSON ? . Me gustaría poder decir que es mejor .. o que es claramente peor . Pero la realidad es que ambas opciones son opciones “validas” .
Eso sí a la hora de diseñar el API REST lo que si es importante es el concepto de homogeneidad es decir una vez que hayamos elegido nuestra opción todos los servicios REST se deben construir de la misma forma ya que simplificará sobre manera su manejo y todos nos encontraremos más cómodos.
El diseño de un API REST es algo que hay que pensar con calma ya que se genera un acoplamiento fuerte.
Hola Cecilio,
Un comentario y una duda.
Respecto a la cuarta forma de devolver el link en el header, entiendo que si el api rest tiene documentación, no debería haber problema en que el cliente supiera consumirlo correctamente.
Y la duda es
En caso de devolver el Link, independientemente como… No implicaría que el back tuviera que saber la estructura de urls del front? En ese caso quedarían un poco acoplados, y en caso de cambio de urls en el front, implicaría cambiar también el back y al reves
Gracias
La url vendría en la cabecera de location . Es decir el cliente leería esa cabecera dinamicamente . Si en una nueva petición la cabecera se actualiza el cliente queda actualizado.
No se si me explico ?