APIs para Dummies: Aprender sobre las API

19 min read
API for dummies

Las interfaces de programación de aplicaciones (API) definen los estándares y protocolos que permiten a los distintos componentes de software comunicarse entre sí. Permiten a las aplicaciones solicitar datos y acciones a sistemas independientes.

Las APIs están en todas partes. Sustentan prácticamente todas las interacciones con tus dispositivos y programas. Por ejemplo, las aplicaciones de su teléfono utilizan APIs para obtener datos de sus servidores y luego dependen de APIs independientes proporcionadas por iOS y Android para poner los datos en la pantalla, enviárselos a través de notificaciones push o compartirlos con un contacto.

Como hay tantas formas de APIs, puede resultar confuso entender cómo se conjugan. ¿Qué tipos de API existen? ¿Cuándo se considera que algo es una API? ¿Cómo puede crear la suya propia? Esta guía completa ofrece respuestas a todas estas preguntas.

¿Qué son las API?

El término interfaz de programación de aplicaciones puede parecer obtuso, pero se refiere a un concepto específico. Una explicación simple es que una API es algo que permite a los desarrolladores programar código que funciona con una aplicación. Establece una interfaz que facilita la interoperabilidad o las reglas, procedimientos, expectativas y normas que deben cumplir dos o más sistemas.

Exploremos esta idea con un ejemplo: consideremos una plataforma de identidad que expone una API para registrar nuevos usuarios. Las aplicaciones externas pueden utilizar la API para crear usuarios bajo demanda, pero para que esto funcione, los datos deben estar en un formato que la plataforma pueda utilizar.

La API establece estos requisitos: puede indicar que la aplicación cliente debe realizar una solicitud HTTP POST a example.com/users; que deben incluirse los campos de datos Nombre, Correo electrónico y Contraseña; y que se emitirá un cuerpo JSON como respuesta, que contendrá el ID del nuevo usuario. Con esta información, los desarrolladores pueden utilizar la API para registrar nuevos usuarios.

Básicamente, una API es una combinación del código de la plataforma que los desarrolladores pueden llamar y la documentación que explica cómo utilizarla.

¿Por qué son importantes las APIs?

Las API permiten que los datos fluyan entre sistemas. Esto permite al software basarse en otras aplicaciones, creando soluciones más potentes.

Las APIs también son esenciales para la automatización. Al combinar las capacidades de distintas APIs en una aplicación, se pueden mover datos entre sistemas a medida que se producen acciones y eventos. Los desarrolladores pueden escribir unas pocas líneas de código para implementar procesos complejos que, de otro modo, requerirían una programación manual laboriosa.

Por ejemplo, el raspado web es una tarea compleja. Para implementar un raspador web eficaz, los desarrolladores tendrían que crear una lógica sofisticada para controlar una instancia del navegador web, configurar proxies de geolocalización y evitar los CAPTCHA. Al seleccionar una API, puede acceder a toda esta funcionalidad con unas pocas solicitudes de red. A continuación, puede utilizar otras APIs para manipular los datos raspados, analizarlos y enviar los resultados a un miembro del equipo en su plataforma de chat.

Además, las APIs son un activo empresarial. Facilitar la integración con otras herramientas hace que sus plataformas sean más atractivas para los clientes. Los desarrolladores externos son libres de construir sus propias soluciones, que son mayores que la suma de sus partes.

Las APIs son de vital importancia para los procesos hiperconectados de hoy en día. Muchas tecnologías que se dan por sentadas funcionan gracias a una intrincada red de APIs. Por ejemplo, las compras en línea suelen implicar APIs de cobro de pagos, solicitudes de envío y entrega de correo electrónico alojadas por varios proveedores independientes.

Tipos de API

Las APIs individuales ofrecen diferentes funciones para adaptarse al servicio del que forman parte. Por ejemplo, una solución de gestión de identidades ofrecerá funciones de API muy diferentes a las de un proveedor de raspado de motores de búsqueda.

Sin embargo, las características técnicas de APIs aparentemente no relacionadas suelen ser muy similares. Las APIs más populares utilizan un puñado de normas diferentes, que representan técnicas que la industria del software ha considerado eficaces para integrar sistemas.

Veamos los distintos tipos de API:

#REST

La transferencia de estado representacional (REST) fue teorizada por primera vez por Roy Fielding en 2000 y ahora la mayoría de los servicios web la utilizan.

REST representa los datos de un sistema como recursos sin estado que se asignan a URL HTTP. Los métodos HTTP (GET, POST, PUT y DELETE) se utilizan para recuperar recursos y realizar acciones sobre ellos.

Por ejemplo, una petición GET a ejemplo.com/usuarios/100 debería devolver la siguiente información sobre el usuario con ID 100:


{
    "Id": 100,
    "Name": "Example User",
    "Email": "[email protected]"
}

Si a continuación se realiza una solicitud DELETE a la misma URL, el servicio debería destruir el objeto.

REST es popular porque es fácil de implementar, se basa en HTTP y modela de forma efectiva cómo muchas aplicaciones del mundo real manejan sus datos. Las interacciones con muchos sistemas suelen ser una combinación de un verbo (DELETE) y un sustantivo (usuario), y esta arquitectura puede expresarse directamente mediante REST.

#SOAP

A diferencia de REST, Protocolo de Acceso a Objetos Simples (SOAP o Simple Object Access Protocol) es una especificación formal para el intercambio de datos. Todos los intercambios SOAP utilizan el formato de datos XML, mientras que las API REST pueden ofrecer JSON, XML, CSV o una alternativa específica de la plataforma. Una simple llamada a la API SOAP podría producir una respuesta como ésta:

xml
<?xml version="1.0" ?>
<soap:Envelope
   	 xmlns:soap="https://www.w3.org/2003/05/soap-envelope/"
   	 soap:encodingStyle="https://www.w3.org/2003/05/soap-encoding">
   	 <soap:Body>
   		 <m:GetUserResponse>
   			 <m:Id>100</m:Id>
   			 <m:Name>Example User</m:Name>
   			 <m:Email>[email protected]</m:Email>
   		 </m:GetUserResponse>
   	 </soap:Body>
</soap:Envelope>

El uso de XML y la inclusión de atributos específicos del protocolo hacen que SOAP sea más verboso que las APIs REST típicas. Sin embargo, las ventajas de la estandarización de SOAP hacen que muchas grandes empresas y sistemas comerciales lo prefieran. Las operaciones disponibles en la API se definen explícitamente mediante esquemas XML. Éstos describen la estructura y los tipos de datos de cada solicitud.

#GraphQL

GraphQL es una tecnología relativamente joven para crear APIs manipulables. Se desarrolló en Facebook en 2012 y se publicó abiertamente en 2015.

GraphQL está diseñada para resolver varios de los problemas de las API REST y SOAP. Simplifica las consultas complejas proporcionando un lenguaje expresivo que el cliente puede utilizar para extraer datos de la API. GraphQL le permite recuperar sólo los campos de datos específicos que necesita en lugar de proporcionar siempre objetos enteros. Así se evitan transferencias inútiles de datos redundantes.

A continuación se muestra una consulta GraphQL sencilla para obtener la dirección de correo electrónico de un usuario:

{
    user {
   	 Email
    }
}

Esta consulta produciría la siguiente respuesta:

json
{
    "user": {
   	 "Email": "[email protected]"
    }
}

GraphQL está ganando popularidad porque es una opción más versátil que se adapta mejor a las aplicaciones altamente conectadas de hoy en día, donde varios componentes diferentes obtienen pequeñas porciones de datos de manera independiente. Sin embargo, la implementación de GraphQL puede ser relativamente compleja y se maneja mejor utilizando herramientas de programación específicas del lenguaje.

#RPC

Las llamadas a procedimientos remotos (RPC) son una forma sencilla de API. La técnica se refiere a llamar a una función remota como si estuviera disponible localmente. Una petición de red básica hace que el servidor API realice la tarea y proporcione el resultado. El cliente no está expuesto a los detalles de la comunicación de red.

Las API RPC tienen un aspecto similar al de las interfaces de programación funcional. Tanto el verbo como el sustantivo se incluyen en la URL a la que se llama, como ejemplo.com/deleteUser?User=100. Esto contrasta con REST, donde se aplica un verbo a un sustantivo específico (DELETE ejemplo.com/usuarios/100). RPC mapea más directamente al código, mientras que REST intenta modelar su estructura de datos.

RPC es fácil de usar tanto para el cliente como para el servidor. Es una colección de URLs que aceptan varios parámetros de petición y envían datos como respuesta. Sin embargo, no existe estandarización y estas APIs suelen ser difíciles de explorar para los desarrolladores. Mientras que los puntos finales de la mayoría de las API REST pueden anticiparse una vez que se conocen los nombres de los recursos del servicio, las URL utilizadas para RPC serán únicas para cada plataforma.

Proyectos modernos como gRPC están introduciendo mejoras en las RPC. Se trata de un marco de trabajo que funciona con múltiples lenguajes de programación y que puede utilizarse para definir rápidamente servicios API RPC que se comunican con los clientes utilizando búferes de protocolo, el enfoque de desempeño de Google para serializar datos estructurados.

APIs de sistemas


Las APIs REST, SOAP, GraphQL y RPC se utilizan en el contexto de las comunicaciones de red entre sistemas. Existen otras API para distintos tipos de integración, como las interfaces de sistema que permiten a las aplicaciones acceder a las funciones de su dispositivo.

Los sistemas operativos como Windows, Android e iOS proporcionan estas APIs. Están expuestas por marcos de programación y SDK que los desarrolladores pueden llamar desde su código. Las API del sistema permiten acceder cómodamente a funciones como las notificaciones, los iconos del launcher, la reproducción multimedia y el acceso a los sensores del dispositivo sin necesidad de que los programadores escriban código de bajo nivel.

API de lenguajes de programación


Del mismo modo, los lenguajes de programación y sus dependencias tienen sus propias API. Los módulos incluidos en la biblioteca estándar de un lenguaje representan una API. También son APIs los paquetes de terceros que se instalan en un proyecto, y los componentes que escribe se conectan entre sí mediante interfaces definidas.

La API es la distinción entre el funcionamiento interno de un sistema, que podría cambiar en cualquier momento, y la interfaz externa estable en la que confían los integradores. Los métodos y funciones marcados como públicos en su código base crean una API que otro código puede consumir.

API síncrona y asíncrona


Las APIs pueden ser síncronas o asíncronas. Una API síncrona devolverá inmediatamente el resultado de la operación solicitada, mientras que una API asíncrona puede continuar la ejecución una vez finalizado el intercambio de datos.

Para una API de recopilación de datos, solicitar los datos recopilados actualmente sería una tarea sincrónica que siempre devuelve los datos recuperados hasta la fecha. La solicitud de una nueva recopilación de datos podría ser asíncrona porque es probable que el proceso tarde mucho tiempo en completarse. Es más eficiente que la API finalice la comunicación inmediatamente después de informar al cliente de que se ha programado la recopilación.

Una mirada detallada: Cómo funcionan las API


Cada uno de los tipos comunes de API tiene su propia gramática. Por ejemplo, REST funciona con objetos y verbos, mientras que GraphQL ofrece una solución más versátil centrada en el cliente en lugar de en el servidor. Veamos con más detalle estas dos opciones:

# REST

REST utiliza verbos de métodos HTTP para realizar acciones sobre los recursos. Los métodos más comunes son GET, POST, PUT y DELETE:

GET /users/100 devuelve el ID con el usuario 100.

POST /users crea un nuevo usuario.

PUT /users/100 actualiza un usuario por ID.

DELETE /users/100 elimina un usuario por ID.

Esto ilustra la sintaxis REST básica. La URL proporciona el ID del objeto con el que se está interactuando y el sustantivo plural del que es una instancia. El método HTTP utilizado por el cliente determina la acción que se realizará.

Cuando una acción requiere datos adicionales para completarse, se suministran como carga útil de la petición HTTP. Por ejemplo, al crear un usuario con POST /users, el cuerpo contendrá el nombre de usuario y la contraseña a asignar.

La API responde a cada solicitud con un código de estado HTTP que describe su resultado. Por ejemplo, una respuesta 404 Not Found a GET /users/100 indica que el ID de usuario 100 no existe, mientras que 202 Accepted para DELETE /users/100 significa que el usuario se ha eliminado correctamente.

#GraphQL

En comparación, GraphQL es un enfoque diferente de las API. Se comercializa como [“un lenguaje de consulta para su API”](https://graphql.org), lo que da a entender la funcionalidad más avanzada que admite. Mientras que REST suele malgastar ancho de banda al incluir propiedades de objetos no deseadas, GraphQL permite solicitar los datos exactos que se desean.

Las API que utilizan GraphQL se crean como servicios, que definen los puntos finales a los que pueden llamar los clientes. Un servicio es un esquema tipificado para una entidad. Cada campo del esquema tiene asignado un tipo de datos específico:

type Team {
    id: ID
    name: String
}

type User {
    id: ID
    name: String
    email: String
    team: Team
}

Se pueden obtener datos de los esquemas mediante consultas:

{
    user(id: 100) {
   	 email,
   	 team {
   		 name
   	 }
    }
}

Este ejemplo de consulta podría devolver los siguientes datos:

{
    "email": "[email protected]",
    "team": "Example Team"
}

Los campos de la consulta están respaldados por resolutores (resolvers). Cuando se ejecuta la consulta, los resolvers se encargan de producir un valor para cada campo. En el ejemplo anterior, el resolutor de team extraería la propiedad name del equipo asignado al usuario solicitado en lugar de devolver el objeto completo.

GraphQL también proporciona una forma coherente de actualizar los datos mediante mutaciones. Las mutaciones son similares a las consultas, pero provocan un cambio de estado en el servidor. Las mutaciones se implementan definiendo una función para cada campo de tus servicios. Esta función es responsable de guardar un nuevo valor en el campo.

Las APIs GraphQL se crean normalmente añadiendo una librería cliente GraphQL a un proyecto. Estas herramientas le permiten generar cómodamente esquemas GraphQL a partir de sus modelos ORM existentes y otro código.

Cómo integrar APIs

Una integración de API describe el proceso de adopción de una API dentro de un sistema de software. Aunque la API ofrece funciones listas para usar, hay que escribir código personalizado para utilizarlas en el proyecto.

Una integración típica de API implica los siguientes pasos:

1. Evaluar las opciones disponibles: para empezar, es necesario evaluar las diferentes APIs que resuelven su caso de uso e identificar la mejor para su producto. Esto incluye analizar la calidad de la documentación, si existe una comunidad activa que utilice la API y la rapidez con la que los responsables responden a las solicitudes de asistencia, los problemas de seguridad y los informes de corrección de errores.

2. Regístrese en el servicio y solicite una clave de API: algunas API están expuestas públicamente y no requieren autenticación, pero la mayoría de las API le exigirán que se registre y obtenga una clave de API una vez que supere algunos umbrales básicos de uso. Las claves API deben tratarse como valores sensibles y almacenarse de forma segura. La clave le autentica ante el servicio e identifica su aplicación a efectos de limitación de tarifas y seguimiento del uso.

3. Busque una biblioteca de clientes API para su lenguaje de programación: puede integrar APIs haciendo peticiones directas a la red utilizando la biblioteca HTTP de tu lenguaje de programación. Sin embargo, muchos proveedores de API también ofrecen bibliotecas cliente y SDK que envuelven la API para ofrecer un lenguaje de programación más cómodo. Si opta por utilizar una biblioteca cliente, simplificará aún más la implementación de una API.

4. Escriba su código: después de identificar la biblioteca, es hora de escribir el código que interactúa con la API. Es necesario configurar la biblioteca con la clave de API obtenida. Es posible que su código también tenga que establecer cualquier parámetro de configuración que requiera el servicio, como la región del centro de datos y el formato de respuesta preferido.

5. Pruebe la integración de la API: por último, pruebe la integración para asegurarse de que funciona como se esperaba. Sus pruebas deben incluir comprobaciones de las rutinas de gestión de errores, como qué ocurre si la API no está disponible. Esto ayudará a garantizar que la aplicación es resiliente cuando el servicio está fuera de línea.

También es importante tener en cuenta las implicaciones de seguridad de integrar una API. Aunque las API de terceros pueden simplificar tareas de desarrollo clave, debe actuar con cautela a la hora de enviar datos de usuario a un servicio externo. ¿La plataforma cumplirá las mismas normas de seguridad que la suya? Si puede replicar fácilmente la funcionalidad de una API, puede ser más seguro crear su propia implementación dentro de su aplicación.

Ejemplo real de API

¿Se dispone a utilizar una API? Para experimentar rápidamente con las API web, se pueden utilizar las herramientas HTTP que ya tiene en su equipo, como curl y wget. Si prefiere las interfaces gráficas, Postman es una buena alternativa.

Obtener datos falsos con Faker

El proyecto Faker API es una popular colección de APIs que devuelven datos generados aleatoriamente sobre diversos temas. La Faker API se utiliza a menudo durante el desarrollo de productos para rellenar interfaces antes de que el backend real esté disponible.

La Faker API utiliza los principios de REST, con el sustantivo al final de la URL que define el tipo de datos a generar:

$ curl https://fakerapi.it/api/v1/books?_quantity=1
{
	"status": "OK",
	"code": 200,
	"total": 1,
	"data": [
    	{
        	"id": 1,
        	"title": "Duck and a pair of.",
        	"author": "Jessyca McKenzie",
        	"genre": "Sit",
        	"description": "ALL RETURNED FROM HIM TO YOU,\"' said Alice. 'I wonder how many miles I've fallen by this time, as it can be,' said the Cat. '--so long as I used--and I don't take this child away with me,' thought.",
        	"isbn": "9796054956226",
        	"image": "http://placeimg.com/480/640/any",
        	"published": "2010-09-14",
        	"publisher": "Quod Enim"
    	}
	]
}

Extracción de listados de motores de búsqueda con Bright Data

Bright Data proporciona un conjunto completo de APIs SERP y APIs proxy, y es una plataforma comercial en la que es necesario registrarse:

Captura de pantalla de la página de API SERP de Bright Data

Para empezar a utilizarla, suscríbase a una prueba gratuita y siga la documentación para añadir la API SERP a su cuenta. A continuación, es necesario activar el modo asíncrono en las Opciones avanzadas de la API:

Infraestructura de raspado web de proxies
Infraestructura de raspado web de proxies

Después de activar la API, puede enviar una solicitud POST para recopilar los resultados del motor de búsqueda:

$ curl -i "https://brightdata.com/api/serp/req?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {API_TOKEN}" \
    -d '{"country":"us","query":{"q":"apis"}}'
...
x-response-id: s3wt2t...

Genere un token de API en la configuración de su cuenta y, a continuación, sustitúyalo en el comando en lugar de `{API_TOKEN}`:

Generar un token de API en Bright Data

Puede encontrar los valores respectivos de los otros marcadores de posición de su cuenta, {CUSTOMER_ID} y {CUSTOMER_ZONE}, en el campo de juego de SERP API.

Este ejemplo de consulta utiliza la API para programar una búsqueda de apis en Google de Estados Unidos. Copia el valor de la cabecera de respuesta x-response-id que aparece en la salida del comando. Este valor se puede utilizar para recuperar el resultado de la SERP una vez generado. Espere un minuto y, a continuación, envíe la siguiente solicitud:

$ curl "https://brightdata.com/api/serp/get_result?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}&output=json&response_id={RESPONSE_ID}"

Sustituya RESPONSE_ID por el valor que ha copiado anteriormente. Los datos generados por su búsqueda se mostrarán en su consola.

Estos endpoints son un ejemplo de una API RPC. Si la API es RESTful, las URL tendrán este aspecto:

POST /api/serp/request y GET /api/serp/results/{RESPONSE_ID}.

Resumen

Las API son interfaces claramente definidas que pueden utilizarse para conectar de forma fiable diferentes componentes de software. Sin embargo, lo que constituye una API puede ser confuso porque hay muchas formas, variantes y casos de uso diferentes.

En general, una API es un mecanismo que el código puede y debe utilizar para acceder a funciones implementadas por otro código. La API está respaldada por el desarrollador del sistema remoto y documentada con instrucciones sobre cómo utilizarla. Esto crea un contrato entre el servicio y las aplicaciones cliente que utilizan la API. Si el cliente envía datos en el formato esperado, se garantiza que obtendrá una respuesta con una estructura predecible.

Las API simplifican la implementación de funciones especializadas en sus sistemas. Puede dejar que los expertos del sector hagan el trabajo duro por usted y luego conectar sus plataformas a su código. Pruebe a utilizar el conjunto de SERP APIs y proxy APIs de Bright Data para realizar sus tareas de raspado web.