API REST, después de esto serás todo un experto

Author
By Darío Rivera
Posted on 2019-11-28 in HTTP
Tags   Laravel 6x

Las comunicaciones entre sistemas por medio de API REST se han ido popularizando rápidamente con los años dejando un poco de lado al antiguo protocolo SOAP. En este artículo, abarcaremos algunos conceptos de los cuáles tal vez hayas escuchado antes tales como REST, API RESTful, Verbos HTTP, entre otros. Por otro lado, te recomiendo revisar nuestro artículo HTTP Básico - Lo que tienes que saber, el cuál mejorará un poco la comprensión de lo que veremos a continuación sin ser requisito.

Qué es REST?

REST (Representational state transfer), o transferencia de estado representativo, es un estilo de arquitectura de software que define una serie de reglas para la comunicación entre sistemas de computadores en la web. Esta serie de reglas, hace más fácil la comunicación ya que la implementación del cliente y del servidor pueden realizarse de manera separada mejorando la flexibilidad de la interfaz a traves de distintas plataformas. 

Los sistemas que son compatibles con REST son llamados RESTful systems, y las APIs expuestas de estos sistemas son llamadas APIs RESTful. Uno de los aspectos más importantes de este estilo de arquitectura, es que al usar una interfaz REST, diferentes clientes que utilizan los mismos endpoints realizan las mismas acciones y obtienen las mismas respuestas.

Peticiones a una API REST

REST requiere que un cliente realice una petición la cuál consta de las siguientes características:

- Un verbo HTTP, que define el tipo de operación a realizar
-Unos encabezados, que definen cierta información acerca de la petición 
-Un camino o recurso (generalmente una URI) 
-Un cuerpo de mensaje (body) opcional que contiene datos 

Verbos HTTP

Existen 4 tipos básicos de verbos HTTP que definen el tipo de operación a realizar.

- GET : Para recuperar un recurso o conjunto de recursos específicos
- POST: Para crear un nuevo recurso
- PUT : Para actualizar un recurso específico
- DELETE : Para eliminar un recurso específico

Encabezados

En los encabezados se envía cierta información acerca de la petición como por ejemplo el tipo de contenido (JSON, XML, ...), la codificación de caracteres, el lenguage, cookies, información de autenticación entre otros. Un encabezado muy común con el que te puedes encontrar sería similar al siguiente.

Content-Type=application/json

En la comunicación mediante REST, el tipo de contenido es esencial. Una petición podría decir qué tipo de mensaje espera mediante el encabezado accept . A su vez, una respuesta generada para dicha petición entregaría un tipo de menasaje definido por el encabezado Content-Type.

Observa la siguiente petición realizada a un servicio que provee información acerca del artículo número 23 en una base de datos.

GET /articles/23 HTTP/1.1
Accept: text/html, application/xhtml

Como se indicó, el encabezado accept permite que la respuesta sea html o xhtml. Los headers enviados como resupuesta del servicio son los siguientes.

HTTP/1.1 200 (OK)
Content-Type: text/html

Como puedes ver el tipo de contenido entregado por el servidor es html, el cual está en la lista de tipos de contenido aceptados por el cliente.

Caminos (PATHS)

Las peticiones deben contener un camino hacia un recurso sobre el cuál será realizada una operación. Los paths deben ser descriptivos e indicar de manera amigable qué operación se está realizando sobre algún recurso. Observa por ejemplo el siguiente path.

someserver.com/customer/10/order/1

Este path, indica en primer lugar el servidor sobre el cuál se realiza la petición. En segundo lugar indica que se está consultando el cliente (customer) con id 10 y la orden número 1.

Cuerpo del mensaje

El cuerpo del mensaje es toda aquella información adicional que se podría enviar en una petición, y toda aquella información que nos devuelve como respuesta un servicio REST. La respuesta a la petición del path indicado anteriormente podría ser la siguiente.

{
    customer: 10,
    order: 1,
    description: 'Purcharse order #1',
    amount: '231.00',
    currency: 'USD'
}

Códigos de respuesta

Toda petición viene acompañada de un código de respuesta HTTP que indica el estado de dicha petición. Los códigos más representativos son los siguientes:

CódigoDescripción
200 (OK)Petición exitosa
400 (BAD REQUEST)La petición del cliente es errónea
403 (FORBIDDEN)El cliente no tiene el permiso para realizar la petición
404 (NOT FOUND)El recurso no puedo ser encontrado
500 (INTERNAL SERVER ERROR)Ocurrió un error en el servidor procesando la petición

Existe un abanico de código intermedios los cuáles puedes consultar con más detalle. Sin embargo, no es necesario que te memorices cada uno de ellos.

A modo de ejercicio podrías utilizar Postman para probar una que otra api pública y practicar lo aprendido. Espero que ahora tengas un poco más claro el término REST, REST API, RESTful system y todos sus derivados. Puedes visitar también nuestro artículo Construye una API REST con Laravel para aplicar lo aprendido. Hasta pronto!.


Si te ha gustado este artículo puedes invitarme a tomar una taza de café

Acerca de Darío Rivera

Author

Ingeniero de desarrollo en PlacetoPay , Medellín. Darío ha trabajado por más de 6 años en lenguajes de programación web especialmente en PHP. Creador del microframework DronePHP basado en Zend y Laravel.

Sólo aquellos que han alcanzado el éxito saben que siempre estuvo a un paso del momento en que pensaron renunciar.