Este primer artículo abarca una breve introducción sobre las solicitudes HTTP (HTTP Requests).
¿Qué es una Solicitud HTTP?
Creo que primero habría que definir que es HTTP (Hipertext Transfer Protocol). El protocolo HTTP no le debe ser muy indiferente. Si leíste sobre el Modelo OSI, recordarás que este protocolo de comunicación pertenece al nivel de aplicación, que a su vez, esta por encima de otro famoso protocolo, el protocolo TCP (Transmission Control Protocol) que se sitúa en la capa transporte de este modelo.
Como todo protocolo de comunicación, el protocolo HTTP define unas normas que debe seguir el emisor que desea transmitir información a un receptor.
HTTP utiliza el patrón de request / response (petición / respuesta), lo cual quiere decir, que un emisor (sistema X) realiza una solicitud (request) y un servidor (Sistema Y) responde (response) a dicha solicitud.
En la siguiente imagen se puede apreciar como un computador (emisor) realiza una solicitud HTTP (HTTP Request) a un servidor (receptor) y este último le responde (HTTP Response) el pedido.
A continuación un ejemplo de las reglas que debe seguir el cliente para que el servidor comprenda su petición HTTP.
POST /v1/customers HTTP/1.1 <-- Linea de Solicitud
Host: api.midominio.com <-- Encabezados ó Headers
Accept: application/json
Content-Type: application/json
Content-Length: 25
<-- 2 lineas
{ <-- Cuerpo ó Body Request
"name": "Pepito S.A.C",
"customer_category": "Grandes Empresas"
}
La primera línea se llama Línea de Solicitud y contiene tres elementos;
- El método HTTP (para este ejemplo es POST).
- Una ruta de acceso (también denominada como endpoint en una API).
- La versión HTTP (para este ejemplo es HTTP/1.1)
Existen otros métodos HTTP, más adelante se mencionarán.
El contenido que le sigue a la «Línea de Solicitud» se denomina Headers (en español encabezados). Los headers son pares de key – value (clave – valor), donde la clave es la primera palabra, seguido de dos puntos y un espacio y, a continuación, el valor.
Los headers están separados por saltos de línea. Es recomendable que las claves de los headers inicien con su primera letra en mayúscula. Los headers pueden repetirse en situaciones en las que es necesario enviar valores duplicados.
Una solicitud HTTP (HTTP Request) solo necesita tener una Línea de Solicitud y algunos headers para ser válido. Esto se aplica principalmente a las solicitudes que utilizan los métodos HTTP GET, DELETE, HEAD y OPTIONS.
Sin embargo, también podemos proporcionar un cuerpo de solicitud (request body), que requiere dos líneas nuevas después del último header antes del contenido del cuerpo. Los cuerpos se utilizan principalmente con los métodos HTTP POST, PUT y PATCH.
Hablemos de los Endpoints
Al diseñar una API HTTP RESTful, es importante poder abstraer la funcionalidad de su servicio de tal manera que todas las operaciones puedan representarse realizando operaciones CRUD (Create, Read, Update, Delete) para los diferentes recursos (entidades). Las acciones (verbos HTTP ó métodos HTTP) que se realizan nunca deben ser parte del endpoint.
El enfoque más utilizado es exponer diferentes colecciones de recursos relacionados. Por ejemplo, si su servicio contiene información sobre diferentes empresas y empleados, podría tener una colección llamada empresas y otra colección llamada empleados.
Podemos obtener información más específica y hacer referencia a una empresa individual o a sus empleados dentro de cada una de estas colecciones. Como por ejemplo, un empleado puede ser empleado en una empresa. Lo siguiente es cómo podemos representar estos datos y sus relaciones:
/companies
/companies/{company_id}
/employees
/employees/{employee_id}
/companies/{company_id}/employees
/companies/{company_id}/employee/{employee_id}
Por lo tanto, podemos decir que si queremos obtener la lista de empresas debemos solicitar el endpoint /companies o si queremos obtener información de solo una empresa debemos solicitar el endpoint /companies/{company_id}
Headers HTTP
Habíamos dicho que los headers son un conjunto de pares de clave-valor. Hay muchos headers diferentes que podemos utilizar. Los navegadores web, por lo general, envían varios headers en sus solicitudes HTTP (requests) y los nuevos navegadores están siendo estandarizados todo el tiempo.
A continuación una lista de los headers más comunes y su significado, que además debe tener en cuenta para que sean compatibles con el API HTTP que construyas.
Accept: Puede contener una lista de «Tipos de Contenido» (Content-Types) que son aceptados por el cliente (navegador web por ejemplo). Un tipo de contenido muy usado en las APIs HTTP es application/json. Es decir, el cliente acepta recibir información del servidor en formato JSON.
Accept-Language: Puede contener una lista de idiomas que son aceptados por el cliente. Por ejemplo podemos indicar que el cliente acepta recibir información del servidor en idioma ingles en-US, o en español es-pe.
Content-Length: Es la longitud en bytes del cuerpo de la solicitud. Si se conoce el tamaño del cuerpo de la solicitud, se debe enviar este valor.
Content-Type: Representa al tipo de contenido proporcionado en el cuerpo de la solicitud. Sólo enviar si la solicitud contiene un cuerpo. Por ejemplo podemos indicar en nuestra solicitud HTTP que la información que vamos a enviar al servidor estará en formato JSON.
Host: Este header siempre se debe enviar en las solicitudes HTTP. Representa al Host HTTP del servidor. Las aplicaciones probablemente ignorarán esto, sin embargo, es sobre todo útil para los hosts virtuales y el enrutamiento de solicitudes.
User-Agent: Este header incluye información de identificación del cliente, como por ejemplo el nombre del navegador web de donde se envía la solicitud HTTP.
GET /companies/twitter/employees/ HTTP/1.1
Host: api.midominio.com
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.5) Gecko/20091102 Firefox/3.5.5 (.NET CLR 3.5.30729)
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: es-pe
Keep-Alive: 300
Connection: keep-alive
Cookie: PHPSESSID=r2t5uvjq435r4q7ib3vtdjq120
Pragma: no-cache
Cache-Control: no-cache
Estos son solo algunos de los headers estandarizados que existen, pero también hay un montón de headers que puedes agregar de manera ad-hoc. Como regla general, al inventar sus propios headers, el patrón común es prefijarlo con una X por adelante, como por ejemplo X-API-Version para representar la versión del API.
Método GET
El método GET hace referencia a la acción de Leer (Read) del CRUD. Las solicitudes GET (GET requests) se consideran seguras, lo que significa que no deben alterar el estado del servidor.
Las solicitudes GET se consideran idempotentes, lo que significa que deben ser repetibles sin causar efectos secundarios. Las solicitudes GET no deben tener un cuerpo (body request).
Cuando se usa el método GET contra una colección (por ejemplo /empresas) significa que deseas recuperar una lista de recursos dentro de esa colección (es decir una lista de empresas).
Podemos recuperar todos los recursos o filtrar recursos específicos según los criterios definidos. El siguiente ejemplo es para obtener obtener una lista de empleados:
GET /companies/twitter/employees?minSalary=3000&maxSalary=8000&perPage=10&offset=20
La solicitud anterior podría traducirse en «Obtener una lista de 10 empleados que trabajan en Twitter que estén en el rango salarial entre 3000 y 8000 (dólares por ejemplo), omitiendo los primeros 20«.
El endpoint contiene parámetros de consulta (filtros) que inician luego del símbolo ? (? Key1 = Value1 & Key2 = Value2). Si no se especifican las propiedades de filtrado (parámetros de consulta), el servidor debe responder con todos los recursos coincidentes.
Es común que los servidores tengan límites por defecto en los datos devueltos, de lo contrario sería muy abrumador devolver todos los datos de una colección, imagina que hubiesen millones de registros :0.
Método POST
El método POST hace referencia a la acción de Crear (Create) del CRUD. Las solicitudes POST (POST requests) se consideran Inseguras ya que alteran el estado del servidor. Se consideran no idempotentes ya que las solicitudes repetidas darán como resultado la creación de varios recursos. Las solicitudes POST deben tener un cuerpo (body request).
Cuando se usa el método POST contra una colección, el servidor debe crear un nuevo recurso dentro de esa colección.
POST /companies
POST /companies/twitter/employees
La primera Linea de Solicitud podemos usarla para agregar una nueva empresa a nuestro servicio.
La segunda Linea de Solicitud podemos usarla para agregar un nuevo empleado a la empresa Twitter.
El cuerpo de la solicitud POST (body request) contendría información sobre el recurso que estamos agregado. Por ejemplo:
POST /companies/twitter/employees HTTP/1.1
Host: api.midominio.com
Accept: application/json
Content-Type: application/json
Content-Length: 57
{
"name":"Gonzalo",
"surname":"Chacaltana",
"twitter_account":"@gchacaltanab"
}
Método DELETE
El método DELETE hace referencia a la acción de Eliminar (Delete) del CRUD. Las solicitudes DELETE (DELETE requests) se consideran Inseguras ya que alteran el estado del servidor.
Sin embargo, se consideran idempotentes, ya que al repetir esta acción DELETE, no debe tener ningún efecto secundario (es decir si por casualidad vuelves a invocar al endpoint con el verbo DELETE, no va eliminar un recurso que ya fue eliminado). Una solicitud DELETE no debe tener un cuerpo (body request).
DELETE /companies/twitter/employees/gchacaltana
DELETE /employees/gchacaltana
La primera Linea de Solicitud es cómo podemos eliminar a un empleado (gchacaltana) de la empresa Twitter.
La segunda Linea de Solicitud es como podemos eliminar a un empleado con identificador gchacaltana.
Métodos PUT/PATCH
Los métodos PUT y PATCH hacen referencia a la acción de Actualizar (Update) del CRUD. Ambos se consideran Inseguros ya que alteran el estado del servidor. Por lo general se consideran Idempotent, es decir si invocamos a la misma solicitud varias veces debe tener el mismo resultado.
Esto es cierto en la situación en la que está proporcionando propiedades de recursos y valores que se reemplazarán en un mismo recurso. Sin embargo, si su servicio tiene la capacidad de modificar una propiedad, como incrementar una propiedad, estas solicitudes se convertirían en no idempotentes. Los métodos PUT y PATCH deben tener un cuerpo.
PATCH /companies/twitter/employees/gchacaltana HTTP/1.1
Host: api.midominio.com
Accept: application/json
Content-Type: application/json
Content-Length: 40
{
"employee_id":"1005400",
"surname":"Pérez Fernández"
}
¿Cuál es la diferencia entre PUT y PATCH?
Generalmente, una solicitud PUT realiza una actualización completa, las propiedades faltantes se actualizarán con valores nulos. Por ejemplo, un recurso de empleado podría tener como propiedades un nombre y un rol, pero realizar un PUT y sólo proporcionar un nombre, tendríamos un rol que falta. A diferencia de una solicitud PATCH, estas solicitudes se usan para realizar actualizaciones parciales.
Sólo se establecerán las propiedades proporcionadas en el cuerpo de solicitud, las propiedades no listadas conservarán su valor existente. Algunas API sólo admiten PUT o PATCH para realizar cualquier actualización.
Métodos HEAD y OPTIONS
Los métodos HEAD y OPTIONS son un poco especiales. Se podría decir que hacen referencia a la acción Leer (Read) del CRUD pero en realidad no recuperan recursos.
Se consideran seguros ya que no alteran el estado de la colección y además son idempotentes, ya que pueden volver a invocarse sin producir malos efectos. Tampoco deben tener un cuerpo de solicitud (body request).
La solicitud HEAD se utiliza para obtener sólo los headers (encabezados) de un recurso. Estos headers pueden contener metadatos útiles como cuando el recurso debe haber caducado. Si el costo de recuperar un recurso es alto (tal vez es un documento grande que es lento para transmitir o tal vez es una costosa llamada de base de datos), entonces podría tener sentido usar una solicitud HEAD en lugar de un GET.
HEAD /employees HTTP/1.1
Host: api.midominio.com
Connection: Keep-Alive
La respuesta (response) del servidor sería:
HTTP/1.1 200 OK
Date: Tue, 27 Jun 2017 12:18:53 GMT
Server: Apache/2.2.14 (Win64)
Last-Modified: Mon, 26 Jun 2017 19:15:56 GMT
ETag: "34aa387-d-1568eb00"
Vary: Authorization,Accept
Accept-Ranges: bytes
Content-Length: 88
Content-Type: text/html
Connection: Closed
En una siguiente publicación, hablaremos más a detalle de los HTTP Response.
La solicitud OPTIONS es útil para servicios expuestos a un navegador, por ejemplo, un navegador cliente puede enviar una solicitud OPTIONS y el servidor responde con headers que especifican que métodos HTTP puede utilizar el navegador y que otras funciones son soportadas por el servidor web. Por ejemplo:
OPTIONS /docs HTTP/1.1
Host: api.midominio.com
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
El servidor podría enviar una respuesta así (HTTP Response).
HTTP/1.1 200 OK
Date: Mon, 27 Jul 2009 12:28:53 GMT
Server: Apache/2.2.14 (Win64)
Allow: GET,HEAD,POST,OPTIONS
Content-Type: httpd/unix-directory
Artículos relacionados: