api-rest 1: introducción a http

Para preparar aplicaciones rest es importante que primero comprendamos cómo funciona el protocolo http

Colette Calascione

archivado en: Internet / 2 noviembre, 2014 / taller:

Internet es un ecosistema complejo donde se establecen cada vez más interrelaciones entre los distintos sitios. Por ejemplo, una web puede estar conectada a la plataforma social facebok para mostrar sus últimas entradas y a twitter y a youtube, y al mismo tiempo proporcionar cosas a otros sitios web. Para que los diferentes sitios puedan dialogar entre sí tienen que hablarse con un lenguaje común. Durante mucho tiempo, este fue el escabroso protocolo soap, pero hoy en día lo normal es que se haga con rest.

Si dejamos al lado los tecnicismos, podemos decir que rest (Representational State Transfer) es una manera de organizar la comunicación en Internet. Son un conjunto de convenciones, de reglas, un tipo de arquitectura de software, que se utilizan para que un servidor que realiza acciones sobre recursos se comunique con distintos ordenadores clientes que le dicen qué debe hacer con esos recursos. Por ejemplo, existe una aplicación rest de Twitter para que los usuarios puedan leer y publicar tweets en esta red desde fuera de https://twitter.com.

Una aplicación rest, por lo tanto, no está ligada a un lenguaje de programación en concreto. Se puede preparar en php, node, ruby... lo único importante es que la comunicación entre el servidor, el suministrador de recursos, y los clientes, los consumidores de recursos, siga unas normas específicas. Y lo más chulo es que los servicios rest son relativamente fáciles de implementar, por lo que está desplazando a otros sistemas como soap, un infierno de código farragoso con una curva de aprendizaje mucho más alta.

El origen de la arquitectura rest se remonta al año 2000, a un texto de Roy Fielding, coautor del protocolo http, y es precisamente en el buen uso de esta especificación donde radica el corazón de una api rest. Por lo tanto, lo primero es comprender qué es y cómo funciona el protocolo http.

Cuando escribimos una dirección web en el navegador del ordenador de nuestra casa, el dispositivo cliente, nos conectamos con otro, el servidor, donde está alojada esa web, y las dos máquinas establecen un diálogo. Y una de las primeras cosas que hacen es ver en qué lenguaje, en qué protocolo, van a comunicarse, que es lo primero que se indica en una URL. Hay varios protocolos, como el file transfer protocol, más conocido por su abreviatura ftp, o el simple mail transfer protocol, smtp. El que nos interesa es el hypertext transfer protocol, que es el que se usa normalmente para navegar por internet.

http://www.geometria.com/poliedros/cuboctaedro.png

Una vez que las dos máquinas saben que van a comunicarse en hachetetepesiano, comienza un intercambio de mensajes (messages), que cuando van del cliente al servidor se denominan request, peticiones, y response, respuesta, cuando van del servidor al cliente. Estos mensajes constan de tres partes:

  1. Una línea inicial (start line), en la que se indican unos datos básicos, como el tipo de acción que se pretende o el resultado de esa acción.
  2. Unas cabeceras (headers), con datos adicionales.
  3. El cuerpo del mensajes (body), que es opcional.

Así, por ejemplo, un ordenador cliente puede emitir un mensaje request que diga algo así:

start line: GET /poliedros/arquimedes.html HTTP/1.1

header: Acept: text/*

Y el servidor puede responder:

start line: HTTP/1.1 200 OK

header: Content-type: text/html

body: <html>... el código html de la página... </html>

Veamos esto con más detalle.

start line

a) Request

En la línea inicial de un request se definen tres cosas. Una es la versión del protocolo http que se está utilizando, otra es la URL, es decir, la dirección, del recurso que se está solicitando, como veremos más adelante, y la tercera es el método, la acción que se debe hacer sobre ese recurso. La acción más habitual es GET, coger, leer, que le indica al servidor que debe enviar el recurso que se está solicitando.

get

En la consola del chrome (F12 y luego la pestaña Network) podemos ver todas las peticiones GET que se realizan cuando visitamos una página web.

Hay ocho métodos, pero de momento solo nos interesan cuatro, los que están relacionados con las operaciones CRUD, esto es, con insertar, seleccionar, actualizar  o borrar algo (Create, Read, Update y Delete). Estos métodos son:

  • GET: para solicitar un recurso.
  • POST: para insertar.
  • PUT: para actualizar.
  • DELETE: para borrar.

Por ejemplo, con esta petición ajax con jQuery le estaríamos indicando al servidor que nos envíe el recurso 24:

$.ajax({

type: "GET",

url: "pagina.php",

data: { id : 24 },

...

Pero así indicaríamos que debe borrarlo.

$.ajax({

type: "DELETE",

url: "pagina.php",

data: { id : 24 },

...

b) Response

Cuando recibe un mensaje request, el servidor realiza las tareas que le indican, como seleccionar algo de la base de datos, y responde con otro mensaje en el que al menos hay otra línea inicial y unas cabeceras. Y en esta línea inicial envía un código de estado que consiste en un número de tres cifras y un texto, una cadena, para indicar qué ha sucedido con la petición. Por ejemplo, si en el request le han pedido un recurso que no existe, responderá con el conocido código 404 indicando que no se ha encontrado.

404

 

Estos códigos se distinguen con facilidad, porque cada rango numérico, cada centena, se corresponde con un tipo de estado. Hay cinco tipos, cada uno de los cuales tiene unos pocos códigos (no hay cien para cada uno):

  1. Del 100 al 199, dan información sobre el proceso;
  2. del 200 al 299, indican que todo ha ido bien.
  3. del 300 al 399, para redirecciones.
  4. del 400 al 499, significa que se ha producido un error del lado del cliente, como pedir un recurso que no existe.
  5. y del 500 al 599, para indicar que el error ha sido del lado del servidor.

No los desgloso aquí, porque están bien explicados en numerosos sitios de internet. En su lugar vamos a analizar las urls.

Anatomía de una URL

Como hemos visto, en la línea inicial del request se indica la url del recurso que se está pidiendo. Como es sabido, una url (uniform resource locator) es la dirección donde se encuentra algo. Por ejemplo, en esta url se encuentra imagen.png:

http://undominio.com/unaruta/imagen.png

Aunque normalmente apenas se manejan unos pocos datos, en una url se pueden incluir un montón de información. Vamos a ir armando una con todo. Lo primero es indicar el protocolo o scheme que se va a usar. En nuestro caso será o http o, su versión segura, https:

http://

Luego, opcional, si fueran necesarios, un nombre de usuario y una contraseña, separados por dos puntos. Se separan del resto de la url por el signo de la arroba (@).

http://nombreUsuario:contraseñaUsuario@

A continuación viene el nombre de dominio y, opcionalmente, Separado por dos puntos, puede indicarse el puerto, que por defecto en http es el 80.

http://nombreUsuario:contraseñaUsuario@www.miDominio.com:80

Luego se indica separada por barras la ruta, el path, que es donde está alojado del recurso a partir del directorio raíz.

http://nombreUsuario:contraseñaUsuario@www.miDominio.com:80/unDirectorio/unSubdirectorio/recurso.html

Tras la ruta, después de un signo de interrogación (?), podemos incluir distintos parámetros de consulta, query strings, que van como pares de clave/valor separados entre sí por el signo ampersand (&). Por ejemplo, así podríamos indicar que queremos el recurso con el id 37 y el color azul.

http://nombreUsuario:contraseñaUsuario@www.miDominio.com:80/unDirectorio/unSubdirectorio/recurso.html?id=37&color=azul

Por último, podemos indicar un fragmento tras poner una almohadilla, como ocurre con las anchors de html, que es un tema que solo influye en el ordenador cliente.

Termino este epígrafe con una aclaración. Una uri (uniform resource Identifier) es un tipo de url que se caracteriza porque el recurso al que apunta no cambia a lo largo del tiempo. Dado que los matices que diferencian una uri de una url en lo que nos atañe son irrelevantes y solo complican un asunto ya de por sí difícil, en esta serie usaré el término url indistintamente.

Headers

Como hemos visto, los mensajes que se intercambian un cliente y un servidor constan de tres partes: una línea inicial (start line), las cabeceras (headers) y, opcional, el cuerpo del mensaje (body). En la línea inicial de la petición (mensaje request) se indica un método, es decir, la acción que se debe realizar con el recurso que se está indicando; y en la línea de la respuesta (mensaje response), un código de estado que indica qué ha pasado con esa petición. Veamos ahora con detalle qué son las cabeceras.

cabeceras

El complemento Live HTTP Headers para Firefox nos permite ver en la consola qué cabeceras se están enviando y recibiendo.

 

Las cabeceras, headers en inglés, están formadas por pares clave:valor. Por ejemplo, esta cabecera enviada en el mensaje response significa que el contenido del body será código html codificado en UTF-8:

Content-Type: "text/html; charset=UTF-8"

Ver todas las cabeceras disponibles en el protocolo http sería suicida tanto para quien esto escribe, como para el que lo lea. Ya iremos viendo las que atañen a rest a medida que vayan surgiendo. Ahora toca ya ir terminando este tocho-post, pero antes quiero recomendar a quien vaya a seguir esta serie que se instale algún http-sniffer, esto es, alguna herramienta que permita visualizar la comunicación http que se establece entre el cliente y el servidor. Hay un montón, pero la que a mí más me gusta es una que conocí gracias a mi amigo Arturo Batanero llamada httpdebugger, de la que existe una demo free con la que ir trasteando durante 15 días.

http debugger, una buena herramienta para trabajar con http

http debugger, una buena herramienta para trabajar con http

|| Tags: ,

valoración de los lectores sobre api-rest 1: introducción a http

  • estrellica valoración positiva
  • estrellica valoración positiva
  • estrellica valoración positiva
  • estrellica valoración positiva
  • estrellica valoración positiva
  • 5 sobre 5 (9 votos)

¿Te ha parecido útil o interesante esta entrada?
dormido, valoración 1 nadapensativo, valoración 2 un poco sonrisa, valoración 3 a medias guiño, valoración 4 bastante aplauso, valoración 5 mucho

Tú opinión es muy importante, gracias por compartirla!

2 respuestas a “api-rest 1: introducción a http

  1. Jacobo el dijo:

    Marcos, sabes que eres mi sensei front-end y te respeto como tal. Pero, si no me equivoco, una URL es un tipo de URI, y no al revés (como menciona el post). Por lo demás el post está fantástico. ¡Muchas gracias, una vez más, por compartir conocimiento de forma tan amena y fluida!