A medida que avanza la tecnología y cada día tenemos más equipos y servicios interconectados, no nos detenemos a pensar ¿como lo hacen?, simplemente hacemos uso de estos equipos y servicios. Pero, ¿que si queremos crear una red de equipos y servicios interconectados para nuestra empresa, nuestro producto o simplemente para simplicar nuestra estructura? Ahí entra el RESTful API o simplemente API.
En esta serie de tres (3) artículos les presentaré el concepto de API, cómo funcionan, para que sirven y cómo creamos uno. Iniciaremos con una breve introducción a RESTful API y el concepto abstracto de los mismos. De esta forma conoceremos no sólo como hacerlo, sino también, por qué hacerlo.
¿Que es un API?
Se conoce como API (del inglés: “Application Programming Interface”), o Interfaz de programación de Aplicaciones al conjunto de rutinas, funciones y procedimientos (métodos) que permite utilizar recursos de un software por otro, sirviendo como una capa de abstracción o intermediario. – Wikipedia
Para quienes vienen iniciando en la programación y desarrollo de software, podemos describir un API, según David Berlind, en su artículo: What is an API, Exactly? como un método generalizado de consumir un servicio. Berlind nos presenta la analogía del conector eléctrico en las paredes de nuestro hogar u oficina. Este conector eléctrico que conocemos permite conectar equipos eléctricos que realizan distintas funciones. Este conector eléctrico es un API. El mismo permite consumir un servicio: electricidad sin importar que equipo lo consuma.
En programación y desarrollo de software o aplicaciones, esta analogía describe perfectamente un RESTful API. Creamos un API con el objetivo de que cualquier software pueda “consumir” nuestros recursos, por lo general datos, sin importar en que lenguaje o plataforma en que sea creado.
RESTful API es el sucesor de métodos anteriores como SOAP y WSDL cuya implementación y uso son un poco mas complejos y requieren mayores recursos y especificaciones al ser usados.
¿Cómo funciona un API?
Un RESTful API, como describimos hace un momento es un servicio. Y si seguimos la analogía del conector eléctrico, entonces fácilmente identificamos que funciona como un estándar para compartir información, en un sistema de doble vía:Consulta y Respuesta (Request -> Response).
Al consultar una API se deben especificar parámetros de consulta para que el servicio sepa lo que queremos consultar, basado en una estructura previamente definida provista por el API por medio de una documentación.
La arquitectura REST (del inglés: Representational State Transfer) trabaja sobre el protocolo HTTP. Por consiguiente, los procedimientos o métodos de comunicación son los mismos que HTTP, siendo los principales: GET, POST, PUT, DELETE. Otros métodos que se utilizan en RESTful API son OPTIONS y HEAD. Este último se emplea para pasar parámetros de validación, autorización y tipo de procesamiento, entre otras funciones.
Otro componente de un RESTful API es el “HTTP Status Code”, que le informa al cliente o consumidor del API que debe hacer con la respuesta recibida. Estos son una referencia universal de resultado, es decir, al momento de diseñar un RESTful API toma en cuenta utilizar el “Status Code” de forma correcta.
Por ejemplo, el código 200 significa OK, que la consulta ha recibido respuesta desde el servidor o proveedor del API. Los código de estado más utilizados son:
- 200 OK
- 201 Created (Creado)
- 304 Not Modified (No modificado)
- 400 Bad Request (Error de consulta)
- 401 Unauthorized (No autorizado)
- 403 Forbidden (Prohibido)
- 404 Not Found (No encontrado)
- 422 (Unprocessable Entity (Entidad no procesable)
- 500 Internal Server Error (Error Interno de Servidor)
Una respuesta de un RESTFul API sería lo siguiente:
Status Code: 200 OK
Access-Control-Allow-Methods: PUT, GET, POST, DELETE, OPTIONS
Connection: Keep-Alive
Content-Length: 186
Content-Type: application/json
Date: Mon, 24 May 2016 15:15:24 GMT
Keep-Alive: timeout=5, max=100
Server: Apache/2.4.9 (Win64) PHP/5.5.12
X-Powered-By: PHP/5.5.12
access-control-allow-credentials: true
Por lo general y mejor práctica, el cuerpo (Body) de la respuesta de un API es una estructura en formato jSON. Aunque también puede ser una estructura XML o cualquier otra estructura de datos de intercambio, incluso una personalizada. Sin embargo, como el objetivo es permitir que cualquier cliente pueda consumir el servicio de un API, lo ideal es mantener una estructura estándar, por lo que jSON es la mejor opción.
El cuerpo de una respuesta estructurada en jSON se vería así:
{
"error": false,
"message": "Autos cargados: 2",
"autos": [
{
"make": "Toyota",
"model": "Corolla",
"year": "2006",
"MSRP": "18,000"
},
{
"make": "Nissan",
"model": "Sentra",
"year": "2010",
"MSRP": "22,000"
}
]
}
La respuesta anterior se obtiene al consultar un API por medio de una ruta o método especifico vía URL. Por ejemplo: http://localhost/api/v1/autos utilizando el método HTTP GET.
Una muestra real de un RESTful API gracias a Facebook:
https://graph.facebook.com/?ids=http://www.nasa.gov
Puedes conocer los shares y comentarios de una URL de un website cualquiera con consultar el API de Facebook desde el navegador.
Y así tenemos una estructura que puede ser “comsumida” desde cualquier plataforma o software sin importar el lenguaje que se utilice, debido a la simple, organizada y estandarizada forma de presentar los datos.
De esta forma funcionan casi todas las aplicaciones en tu smartphone, o servicio como Facebook, Instagram, Snapchat, Messenger, etc. o cualquier otro servicio que permite a terceros utilizar sus recursos.