Desde que se introdujo en Visual Studio el soporte para archivos .http, he estado usando esta funcionalidad del IDE para probar APIs, dejando casi totalmente de lado a herramientas que había utilizado siempre como Postman o Fiddler. Es genial tenerlo todo en el mismo entorno, que sea tan sencillo de utilizar, y que se integre tan bien con otras herramientas del ecosistema, como el endpoint explorer, user secrets de ASP.NET Core, Azure key vault, etc.

Sin embargo, una limitación importante era que sólo podíamos declarar y asignar variables, pero éstas no podían ser modificadas en tiempo de ejecución. Esto hacía que, por ejemplo, no pudiéramos hacer una llamada a un endpoint de autenticación y utilizar luego el token retornado para acceder a determinados recursos, por lo que teníamos que hacerlo manualmente.

Pero esto cambió con la versión 17.12 de Visual Studio 2022, donde se ha añadido la posibilidad de poder capturar valores de la respuesta de una petición para utilizarlos más adelante en otras peticiones.

Como sabemos, en las peticiones HTTP se envían al servidor un conjunto de “parámetros” o encabezados que añaden información extra para que la solicitud pueda ser procesada correctamente. Ahí encontramos información sobre el lado cliente, como la cadena de agente de usuario (encabezado user-agent), información sobre la propia petición, como el host al que se dirige la petición (encabezado host) o los idiomas que se aceptan para el contenido (accept-language), e incluso información contextual como las cookies del usuario (cookie) o información de autorización (authorization), entre muchos otros.

Hoy vamos a detenernos en una curiosidad histórica sobre el protocolo HTTP y uno de sus más célebres encabezados :)

Los que lleváis tiempo programando APIs HTTP, ya sea con ASP.NET Core o con otras tecnologías, seguro que en muchas ocasiones habéis tenido que decidir cómo retornar al cliente, de forma más o menos normalizada, los errores producidos en el lado servidor.

Lo habitual es echar mano de los status code de HTTP para indicar problemas en el proceso de una petición; de hecho, este protocolo dispone de un rico conjunto de códigos que en principio parecen cubrir todas nuestras necesidades.

Pero no siempre es así. Por ejemplo, si tenemos un servicio que permite a los clientes de una empresa formalizar un pedido a través de un API y una llamada a este servicio retorna un error HTTP 403 (forbidden), claramente estamos indicando que el solicitante no tiene permisos para hacer un pedido. Sin embargo, no tenemos una forma clara de indicar cuál es la causa de esta prohibición (¿quizás las credenciales no son correctas? ¿o quizás el cliente no tiene crédito en la empresa? ¿o puede ser que el administrador lo haya denegado expresamente?)

Para aportar más detalles sobre el problema, normalmente necesitaremos retornar en el cuerpo de la respuesta información extra usando estructuras o formatos personalizados, probablemente distintos de una aplicación a otra, y documentarlos apropiadamente para que los clientes puedan entenderlos. Y aquí es donde entra en juego el estándar “Problem details”.

Como sabemos, los conocidos códigos de estado HTTP 301 y 302 se usan para retornar al agente de usuario (normalmente, el navegador) una redirección, que viene a ser algo así como decirle “hey, el recurso que andas buscando ya no se encuentra aquí, sino en esta otra dirección”.

Presto y obediente, el browser interpretará esta orden navegando hacia la URL indicada en el encabezado location del resultado, es decir, generando una nueva petición de tipo GET y mostrando al usuario la página obtenida.

Un ejemplo del workflow de peticiones y respuestas de este tipo podría ser la siguiente:

// Petición:
GET /home/articles/welcome-to-my-blog.html HTTP/1.1
Host: www.myserver.com

// Respuesta:
HTTP/1.1 301 Moved Permanently
Location: http://www.myserver.com/blog/welcome-to-my-blog.html

// Nueva petición:
GET /blog/welcome-to-my-blog.html HTTP/1.1
Host: www.myserver.com
...

La diferencia entre el código 301 y 302 es que el primero de ellos indica al agente de usuario (sea un browser o aplicación cliente) que la redirección es permanente, esto es, que puede almacenar localmente la nueva ubicación y utilizarla en el futuro con seguridad en lugar de la que se usó originalmente. El código 302, en cambio, indica que la nueva ubicación es temporal y sólo debe ser utilizada en esta ocasión para dirigir la petición al lugar correcto.

Los códigos de estado HTTP 301 y 302 son válidos en la mayoría de escenarios, y permiten solucionar problemas como, entre otros, el cambio de ubicación nuestros recursos sin perder posicionamiento en buscadores, o implementar el patrón Post-Redirect-Get para mejorar un poco la experiencia de usuario y evitar dobles envíos de información en formularios.

Sin embargo, hay ocasiones en que la solución queda algo corta. Por ejemplo, si cambiamos de URL el endpoint de un servicio programado exclusivamente para ser invocado mediante peticiones de tipo POST o PUT, lo que nos interesaría sería que las peticiones a la dirección original retornaran una redirección indicando la nueva ubicación pero también informando al browser de que utilice sobre ella el mismo verbo de la petición original.

Por ello, y algunas otras razones que veremos después, el estándar HTTP amplió, hace ya bastante tiempo, el conjunto de códigos de redirección con tres nuevos miembros: HTTP 303, 307 y 308. Los dos primeros formaron parte de HTTP 1.1, mientras que el código 308 fue añadido en la RFC 7538 algo más adelante.

Veamos para qué sirve cada uno de ellos.