API’s a Detalle

En nuestro capitulo anterior ya platicamos sobre la importancia de las API’s en las empresas y los grandes beneficios que aportan. Hoy hablaremos más a detalle sobre sus características, su composición y los diferentes tipos que existen. Sera una vista más técnica, pero con explicaciones sencillas para su mejor comprensión.

Tipos de APIs

Actualmente existen diferentes tipos de API’s, pero nos centraremos en las más comunes y estas son:

• REST API: Estas son las más populares, gracias a su flexibilidad. Funcionan de la siguiente manera. El cliente envía una solicitud con sus respectivos datos al servidor, el servidor utiliza esta petición y entrada de datos para realizar funciones internas y devuelve una respuesta con la descripción y el estatus de las acciones realizadas al cliente. Este intercambio de información generalmente es en formato JSON, pero se puede configurar a cualquier otro formato deseado.
• SOAP API: Esta es una API menos flexible que fue muy popular en el pasado. Con este tipo de API el cliente y el servidor intercambian mensajes en formato XML.

De acuerdo al ámbito de uso también existen diversos tipos de API’s como los siguientes:

• API Privadas: Estas solo se utilizan internamente en una empresa, es decir solo la empresa tiene el acceso y control total de este tipo de API.
• API Publicas: Este tipo de API’s está abierto al público, para que otras empresas puedan utilizarlas y aprovecharlas para crear servicios innovadores. Las API´s de este tipo pueden ser gratuitas o de pago.
• API de socios/partners: Estas API’s se comparten únicamente con socios empresariales con el objetivo de proporcionar flujos de ingreso adicionales o para el cumplimento de algún proceso de negocio en favor de alguno de los socios.

A partir de este punto vamos a hablar únicamente de las API’s más populares (REST API’s) ya que son con las que nos vamos a encontrar más a menudo en las empresas.

Significado de REST

Por sus siglas en inglés (Representational State Transfer) se traduce como [Transferencia de Estado Representacional] esto significa que las API’s de este tipo no tienen estado, pero que es el estado? Tomando como ejemplo un sitio web de compras, cuando un usuario inicia sesión (ingresa con usuario y contraseña) al sitio o aplicación, el servidor almacena ciertos datos del usuario para poder brindarle una experiencia personalizada, estos datos pueden ser: su historial de compras, su lista de deseos, los productos en su carrito de compras y también se almacenan los tokens de sesión generados al momento de ingresar a la app, estos datos son almacenados en memoria o en disco dependiendo del tipo de información. Todo esto con el fin de que la interfaz de usuario y el servidor puedan operar de forma eficiente.

Debido a que las REST API’s son sin estado, esto significa que en cada solicitud el cliente debe incluir toda la información necesaria para que el servidor pueda procesarla. Con esto podemos afirmar que este tipo de API’s no requieren de la creación de una sesión en el lado del servidor para poder interactuar y además debido a la ausencia de estado el servidor no almacena ningún tipo de información del cliente.

REST es también un estilo de arquitectura que trabaja sobre el protocolo HTTP y se compone de una serie de reglas que las API’s deben cumplir para ser consideradas REST API’s. A continuación, se listan estas reglas:

• Interfaz uniforme: Interfaz basada en recursos, todas las solicitudes para el mismo recurso deben ser iguales, sin importar el origen de la petición. También debe utilizar mensajes descriptivos apoyándose de la semántica del protocolo HTTP como son el uso de URI, métodos, verbos, códigos de estado, campos de cabeceras y demás.
• Peticiones sin estado: El cliente debe enviar toda la información necesaria al servidor para que su petición sea procesada. Las REST API’s no requieren de la creación de ninguna sesión para poder interactuar con el servidor. El servidor no puede almacenar ningún dato del cliente relacionado con una solicitud.
• Almacenamiento en Caché: Se refiere a la capacidad de almacenar los recursos en la memoria cache ya sea en el lado del cliente o el servidor siempre que sea posible o permitido para el recurso en cuestión. Todo con el objetivo de mejorar el rendimiento en el lado del cliente y al mismo tiempo aumentar la escalabilidad en el servidor.
• Separación de cliente y servidor: Se traduce a que las aplicaciones cliente y servidor deben ser completamente independientes entre sí y lo único que el cliente debe saber es la URI del recurso al cual quiere acceder de la aplicación servidor. De la misma manera la aplicación del lado del servidor no debe modificar la aplicación cliente, solo debe entregar los datos solicitados vía HTTP.
• Sistema de capas: Hace referencia a que en las interacciones entre el cliente y el servidor pueden estar mediadas por capas adicionales con el fin de añadir seguridad, escalabilidad, como el uso de balanceadores de carga o caches compartidos.
• Código bajo demanda (opcional): Las aplicaciones del lado del servidor pueden ser capaces de aumentar o definir cierta funcionalidad en el cliente transfiriéndole cierta lógica que pueda ejecutar, estas pueden ser applets de Java o código JavaScript.

Componentes de una REST API

Sabias que a las REST API’s también se les considera como contratos!, esto es también porque su documentación representa un acuerdo entre las partes involucradas, si una de las partes envía una solicitud con una estructura en particular, esa misma estructura más el método y la URI a la que se envía determinaran las acciones y la respuesta de la otra parte.

En el párrafo anterior seguramente encontraste palabras que no son muy comunes, pero no te preocupes enseguida veremos sus significados y algunos ejemplos.

Solicitud: También conocida como petición se refiere a la acción de ejecutar una llamada a un endpoint, acompañada de un método a ejecutar más la estructura que contiene la información que enviaremos a la API. Esta solicitud o petición se realiza con un cliente REST o con librerías REST con las que cuenta casi cualquier lenguaje de programación. Algunos clientes REST más populares son Advanced REST Client, Postman y SoapUI.

URI: URI significa “Identificador de Recurso Uniforme”, es un identificador que hace referencia a un recurso en internet. También es conocido como endpoint o URL.

Ejemplo: http://api.e-bookmobile.com/v1/empleados

El ejemplo nos da a entender que estaremos interactuando con el recurso empleados.

Recurso: El estilo de arquitectura REST trata a cada contenido como un recurso, algunos ejemplos de recursos pueden ser datos dinámicos de una organización (almacenados en archivos o en tablas de bases de datos), imágenes, videos, paginas HTML, etc. Un recurso en una REST API es similar a un objeto como en Programación Orientada a Objetos con la diferencia de que a un recurso solo se le pueden aplicar métodos estándares definidos por el protocolo HTTP, mientras que los objetos tienen demasiados métodos, tantos como la lógica de negocio lo requiera.

Un recurso puede tener relaciones con otros recursos y también pueden ser agrupados en colecciones, estas colecciones también las podemos ver como grupo o conjunto de recursos.

Las REST API’s pueden definir los recursos en diferentes estructuras o formatos estándares, los cuales veremos a continuación.

Estructura: También conocida como payload. Es la representación del recurso en un formato estándar, el cual es consensuado con el cliente que utilizara la REST API. Los formatos que más utilizan son JSON, XML, CSV y texto plano.

Cabeceras/Encabezados: Contienen metadatos en forma de clave-valor que contribuyen al correcto procesamiento de la solicitud. Ejemplos de estos metadatos podrían ser: el formato en el que se enviara la estructura, credenciales de acceso a la API, configuraciones de cache, etc

Parámetros: Los hay en dos tipos:

• Parámetros URI: Son utilizados como identificadores de recursos es decir que solo debe existir un único recurso con ese identificador. Este tipo de parámetros se incluyen justo después del nombre de un recurso. Ejemplo /empleados/315 esto quiere decir que solo estaremos interactuando con la instancia del recurso empleado con identificador 315.
• Parámetros de consulta: Estos son pasados al final de la URL después de un signo de interrogación y son utilizados para ordenar, filtrar o paginar una colección de recursos. Ejemplo /empleados?edad=20 utilizando este parámetro estaremos interactuando con la colección de empleados que tengan 20 años de edad.

Métodos: Son los definidos por el protocolo HTTP. Estos se utilizan para realizar operaciones básicas en un recurso como leer, crear, actualizar y eliminar. Los más comúnmente utilizados son:

• GET (Leer u obtener)
• POST (Crear)
• PUT (Actualizar)
• Delete (Eliminar)

Es importante mencionar que el payload y las cabeceras también estarán presentes en la respuesta de la API, acompañados por un código de estado HTTP. Estos códigos son estándares del protocolo HTTP y su función es informar el estado de la petición, los códigos más comunes son los de Información (100–199), Éxito (200–299), Redirección (300–399), Error del Cliente (400–499) y Error del Servidor (500–599).

Ahora que usted ya conoce un poco más sobre las APIs, esta listo para implementarlas y en nuestro siguiente capitulo le platicare de como hacerlo de forma sencilla, ágil y segura en la plataforma numero uno del mercado.