Comprender las plataformas basadas en API: una guía para gerentes de productos

Construir un producto digital hoy es integrar la miríada de varios sistemas administrativos con puntos de contacto y dispositivos del cliente. El costo de contratar a un equipo de software para conectarlos en una única solución de trabajo podría dispararse.

Esta es la razón por la cual los gerentes de productos modernos, al elegir proveedores, a menudo dan prioridad a las capacidades de integración, lo que puede reducirse a elegir sistemas que expongan API. ¿Qué es la API y cómo probarla sin involucrar a su equipo técnico? sigue leyendo

Adopte los datos: por qué necesitamos las API

Los datos de los clientes cambian la forma en que opera el negocio. Si se recopilan y distribuyen correctamente, pueden ayudar a las empresas a aumentar las tasas de adquisición y retención de clientes, lo que eventualmente conducirá a una explosión de ingresos.

Pero el procesamiento de datos es un trabajo tedioso. Es por eso que los negocios recurrieron a la informática. En la década de 1990, las bases de datos que automatizaban las tareas de datos que consumían más tiempo se volvieron enormemente populares en los departamentos de marketing. Esto condujo a un cambio masivo en la forma en que se concibieron las estrategias de marketing; ese cambio se denominó enfoque basado en datos .

Sin embargo, las bases de datos tenían una desventaja importante. Para convertirlos en algo de valor, una empresa necesitaba contratar ingenieros de software. Eran los héroes que sabían cómo convertir grandes cantidades de datos en conocimientos prácticos. También eran los guardias que protegían la integridad de los datos y, por lo tanto, se aseguraban de que el sistema estuviera preparado para el futuro.

Pero los ingenieros de software cuestan mucho y su interfaz de comunicación requería esfuerzo.

Cuando la cantidad de canales de recopilación de datos se extendió por varios departamentos e incluso empresas externas, las bases de datos y sus operadores se convirtieron en un cuello de botella. Las empresas necesitaban encontrar una forma automatizada de acceder a los almacenes de datos.

Así es como se originó la idea de los primeros sistemas API.

Qué es realmente la API sin la jerga tecnológica

Los primeros sistemas API, hoy comúnmente abreviados como API (Interfaz programable de aplicaciones), son las aplicaciones que aseguran que otros sistemas puedan acceder a sus datos de una manera unificada y segura.

Sin una calificación en ciencias de la computación, la interfaz programable de aplicaciones realmente no le suena familiar. Echemos un vistazo a una explicación más tangible.

Una de las mejores analogías que he encontrado en la web hasta ahora ha sido escrita por Taija:

“Si vas a un restaurante como cliente, no tienes permitido entrar a la cocina. Necesitas saber lo que está disponible. Para eso, tienes el menú. Después de mirar el menú, le haces un pedido a un mesero, quien lo pasa a la cocina y luego te entregará lo que le has pedido. El mesero solo puede entregar lo que la cocina puede brindar.

La mejor analogía de API que he visto: toma un restaurante. El menú es la API, tu pedido es la llamada de la API, la comida de la cocina es la respuesta.

— ¡Aarthi 發財! (@AarthiD) 19 de diciembre de 2013

¿Cómo se relaciona eso con una API? El camarero es la API. Eres alguien que está pidiendo servicio. En otras palabras, usted es un cliente o consumidor de API. El menú es la documentación que explica lo que puede solicitar de la API. La cocina es, por ejemplo, un servidor; una base de datos que contiene solo cierto tipo de datos: lo que el comprador haya comprado para el restaurante como ingredientes y lo que el chef haya decidido que ofrecerán y lo que los cocineros saben preparar”.

Así que de nuevo:

• Cocina
  La base de datos, ningún cliente permite proteger la integridad de los datos.
• Mesero
  La API, un intermediario que sabe cómo servir los datos de la base de datos sin interrumpir su funcionamiento.
• Cliente
  Un sistema externo que quiere obtener sus datos.
• Menú
  La referencia de formato de datos que los sistemas externos deben utilizar para realizar su operación.
• Pedido
  Una única llamada API real.

Con el estado actual de la tecnología, todavía se necesita un desarrollador de software para "hacer un pedido". Pero es mucho más rápido (léase: más barato) porque el menú, como el de McDonald's, está más o menos estandarizado en todo el mundo.

Así que ahora, vamos a ponernos en el lugar de un desarrollador de software e intentar llamar a una API ejemplar. No te preocupes; no vamos a ir más allá de las clases de informática de la escuela.

Cómo obtiene los datos su aplicación meteorológica: conceptos básicos de la API

Vamos a descubrir cómo su aplicación meteorológica conoce la temperatura actual. De esta forma, obtendremos los conceptos básicos de cómo comunicarnos con sistemas a través de Internet.

Lo que necesitamos:

• Una base de datos meteorológica
• Un navegador
• Una pizca de fuerza de voluntad

¡Eso es todo! La tecnología actual facilita la prueba de la API sin necesidad de grandes herramientas de desarrollo.

Por supuesto, eso es diferente cuando desea crear una integración completa. Cuando llega el momento, necesita conocer herramientas y lenguajes de programación más avanzados, pero para pruebas/pruebas de conceptos, esta configuración es suficiente.

Por lo tanto, intentemos obtener el índice de temperatura actual de su ciudad o, en la jerga de los codificadores, invoquemos la primera llamada a la API. Después de todo, todo se reduce a enviar un mensaje de texto a un servidor y recibir un mensaje a cambio .

La anatomía de una solicitud de API

En este artículo, usaremos la API https://openweathermap.org. Visite el sitio e intente verificar las condiciones climáticas en varios lugares. Con suerte, te sientes mejor que yo en Katowice hoy:

Como habrás adivinado, el sitio web está llamando a la API para obtener los datos. Los desarrolladores lo implementaron de manera que cada vez que presionas buscar , detrás de escena, la aplicación llama a la puerta de la API y dice "dame la temperatura de <ciudad>".

Pongámonos un sombrero de hacker y veamos las llamadas API que este sitio web está llamando con su navegador. Puede usar las herramientas de desarrollo en su navegador para ver lo que sucede detrás de escena:

1. En Chrome, vaya a Menú → Más herramientas → Herramientas para desarrolladores;
2. Cambiar a la pestaña Red;
3. Intente verificar la temperatura en diferentes ciudades en el widget de arriba;
4. En la lista en la parte inferior, notará enlaces que han sido llamados:
   

   

   
   Si copia el enlace, puede ver que incluye el nombre de la ubicación y un par de otros parámetros.
   

    https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

5. Cuando pegue el enlace en la barra de direcciones del navegador, debería ver las respuestas de la API con:
   

    jQuery19103887954878001505_1542285819413({"message":"accurate","cod":"200","count":1,"list":[{"id":3096472,"name":"Katowice","coord":{"lat":50.2599,"lon":19.0216},"main":{"temp":281.69,"pressure":1031,"humidity":61,"temp_min":281.15,"temp_max":282.15},"dt":1542285000,"wind":{"speed":3.6,"deg":50},"sys":{"country":"PL"},"rain":null,"snow":null,"clouds":{"all":90},"weather":[{"id":804,"main":"Clouds","description":"overcast clouds","icon":"04d"}]}]})

6. Es un poco caótico, pero si quita el contenido de los paréntesis y lo ejecuta con un formateador de datos, verá una estructura que tiene sentido:
   

    { "message":"accurate", "cod":"200", "count":1, "list":[ { "id":3096472, "name":"Katowice", "coord":{ "lat":50.2599, "lon":19.0216 }, "main":{ "temp":281.69, "pressure":1031, "humidity":61, "temp_min":281.15, "temp_max":282.15 }, "dt":1542285000, "wind":{ "speed":3.6, "deg":50 }, "sys":{ "country":"PL" }, "rain":null, "snow":null, "clouds":{ "all":90 },

7. La respuesta de la API es una estructura de datos con información sobre las condiciones climáticas actuales: debe descifrar fácilmente la mayoría de los parámetros. Este formato de datos se llama JSON . Esta es una notación importante porque la mayoría de las API modernas la usan. Esta pila de identificaciones y corchetes tiene un propósito: es más fácil para una aplicación analizar un mensaje bien estructurado que un texto colocado al azar.

Una palabra de explicación de lo que acabamos de hacer aquí.

La aplicación web detrás del sitio web Open Weather Map toma los datos de la API y los muestra en el sitio web.

Cada vez que escribes el nombre de la ciudad y presionas buscar , el sitio web se conecta a un servidor con un enlace específico que incluye el nombre de la ciudad como parámetro.

La misma oración en la jerga tecnológica: la aplicación detrás del sitio web envía una solicitud a un extremo de la API proporcionando el nombre de la ciudad como argumento .

Luego, la API responde (envía una respuesta de la API ) con un mensaje de texto con formato JSON .

Para crear una solicitud de API, debe reunir su dirección. Sí, la dirección es una buena analogía. Para enviar algo, debe proporcionar al servicio de mensajería:

• Ciudad,
• Calle y número,
• A veces, alguna información adicional sobre cómo llegar a su oficina.

Y, para conectarse a la API, por analogía, necesita:

• https://openweathermap.org/ (enlace) La ciudad o el punto final raíz: un punto de partida, una dirección de Internet de un servidor al que desea conectarse, en nuestro caso.
• data/2.5/find (enlace) El número de calle o la ruta: determina el recurso que desea obtener de una API.
• Callback=jQuery19103887954878001505 1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22& =1542285819418

Así es como se diseñan las API. El punto final raíz generalmente permanece igual para un solo proveedor, luego debe averiguar qué ruta y parámetros de consulta están disponibles y qué información el equipo de desarrollo de API puso detrás de ellos.

Ahora pongamos el sombrero de hacker un poco más apretado. En nuestro caso, no todos los parámetros de consulta son necesarios para obtener los datos meteorológicos. Intente eliminar diferentes parámetros después del signo de interrogación ( ? ) y compruebe cómo responde la API meteorológica.

Por ejemplo, puede comenzar eliminando la callback de llamada del enlace de solicitud:

 https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

El resultado:

 https://openweathermap.org/data/2.5/find?q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

Si juegas con los otros, puedes ver que algunos de ellos también son opcionales. En realidad, solo q y appid son obligatorios:

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

¿Cómo saber qué es obligatorio y qué es opcional? ¿Cómo sabe dónde obtener el punto final raíz y la ruta en primer lugar?

Documentación API: una lectura obligada antes de comenzar

Siempre debe consultar primero la documentación de la API para aprender cómo construir su solicitud de la manera correcta.

En nuestro caso, la documentación https://openweathermap.org/current muestra los puntos finales disponibles. También explica todos los campos de datos de respuesta, para que pueda encontrar qué información responderá la API incluso antes de enviar una solicitud.

Una buena documentación de API ofrece tutoriales de inicio rápido sobre cómo crear solicitudes simples y pasa a cosas más avanzadas. Afortunadamente, Open Weather API tiene una y la vamos a usar ahora.

Creación de una llamada API desde cero

Resumamos nuestros hallazgos. Ya hemos enviado una solicitud a la API. Hemos descubierto el enlace correcto al oler lo que OpenWeatherMap hace detrás de escena. Este enfoque se denomina ingeniería inversa y, a menudo, es difícil o no es posible en absoluto.

Además, la mayoría de las veces, los proveedores de API prohíben a los usuarios el uso excesivo de esta opción. Es por eso que debemos aprender cómo "llamar" a la API según las reglas (es decir, documentación).

Una forma de hacer esto es codificarlo. Pero como no somos programadores ( ¡todavía! ), vamos a utilizar herramientas que lo hagan más fácil. Mucho más fácil que incluso los desarrolladores de software lo tienen bajo su cinturón de herramientas.

Como prometimos, no dejaremos el navegador. Pero necesitamos instalar una extensión (solo Chrome): Postman. Este complemento simple convierte su navegador en un conector API.

Bien, ahora que tenemos una herramienta, echemos un vistazo a la documentación para ver cómo podemos obtener las condiciones climáticas actuales para un nombre de ciudad específico https://openweathermap.org/current#name .

Los documentos dicen que debemos usar el siguiente punto final: api.openweathermap.org/data/2.5/weather?q={city name}

Cuando lo desglosamos obtenemos los siguientes elementos:

• Punto final raíz: api.openweathermap.org
• Ruta: data/2.5/weather
• Parámetro de consulta: q={city name} (esta noción significa que debemos reemplazar las llaves con el nombre de una ciudad específica)

Pongámoslo en Postman. El proceso se reduce a tres sencillos pasos:

1. Haga clic en 'Solicitar' en el menú superior.
   

   

2. Asigne un nombre a su solicitud y proporcione el nombre del catálogo en la sección en la parte inferior también.

   

3. Pegue el extremo de la API al que desea llamar, haga clic en Enviar y debería ver la respuesta de la API en la sección Respuesta:

   

¡Felicitaciones! Acabas de llamar con éxito a tu abeto... ¡espera un segundo! Prestemos atención a la respuesta de la API:

No es un JSON lleno de información meteorológica que hayamos visto antes. ¿Qué significan el 401 y la clave de API no válida? ¿Está mal nuestra documentación?

Autenticación

No dejarías que nadie acceda a tu gabinete de cócteles sin tu permiso, ¿verdad? Del mismo modo, los proveedores de API también quieren controlar a los usuarios de su producto para protegerlo de actividades maliciosas. ¿Qué es la actividad maliciosa? Por ejemplo, enviar muchas solicitudes de API al mismo tiempo, lo que "sobrecalentará" el servidor y provocará tiempo de inactividad para otros usuarios.

¿Cómo se puede controlar el acceso? ¡De la misma manera que guardas tus bebidas! Mediante el uso de claves: claves API .

Si visita la guía Cómo comenzar de la documentación de Weather API, notará cómo puede obtener su clave. Regístrese ahora y revise su bandeja de entrada.

Entonces ahora la pregunta es ¿cómo usar la llave? Es fácil, de acuerdo con los documentos, simplemente copie y pegue la clave al final de la URL de su punto final (sin llaves).

 api.openweathermap.org/data/2.5/weather?q=Katowice&appid={your API key}

Y haz clic en enviar de nuevo. ¡Aquí tienes, ahora podemos ver la respuesta de la API!

Pero hay mucho más que puede obtener de la API usando Postman. ¿Listo para convertirte en un verdadero hacker de API?

Parámetros de la API: Obtención de respuestas personalizadas

Por lo general, los puntos finales de la API tienen algunas funciones de utilidad que puede usar para ajustar la respuesta de la API, por ejemplo, si necesita un mejor formato de datos o desea obtener los datos en un orden particular. Estas opciones suelen estar ocultas detrás de algunos parámetros que puede encontrar en la documentación.

Los parámetros de consulta son solo un texto estructurado que agrega en la dirección del punto final con el siguiente patrón:

1. Un signo de interrogación ( ? ) después de la ruta,
2. Nombre de un parámetro,
3. Símbolo de igual a ( = ),
4. Valor del parámetro,
5. Ampersand ( & ) y otros siguen con los puntos 2-4 (de esta manera puede agregar tantos parámetros como desee).

Tome nuestra primera solicitud como ejemplo:

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Nota importante: el orden de los parámetros de consulta no importa.

 ?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Lo anterior es igual a lo siguiente:

 ?appid=b6907d289e10d714a6e88b30761fae22&q=Katowice

Como se mencionó, los parámetros de consulta se describen en los documentos de la API. El siguiente extracto de la documentación de la API meteorológica le muestra cómo obtener la temperatura en diferentes unidades (imperiales o métricas):

Intente enviar estas dos opciones con Postman para ver la diferencia en los resultados. Recuerde agregar su clave API al final de la dirección del punto final.

Nota : Siempre tómese un tiempo para estudiar la documentación y encontrar parámetros que puedan ahorrarle a usted o a su equipo de desarrollo mucho tiempo.

Opciones de solicitud de API: cómo enviar datos a la API

Hasta ahora, hemos estado obteniendo información de la API. ¿Qué sucede si queremos agregar o modificar información en la base de datos detrás de la API? Los métodos de solicitud son la respuesta.

Echemos un vistazo a Postman una vez más. Es posible que haya notado una etiqueta GET en mayúsculas junto a la dirección del punto final de la API. Esto representa uno de los cuatro métodos de solicitud. GET significa que queremos obtener algo de la API (gracias capitán) y es una opción predeterminada. ¿Cuáles son las otras opciones?

¿Todavía confuso? Pasemos a los ejemplos.

API POST: Cómo crear un registro en la API

No podemos crear ni actualizar nada con Weather API (porque está destinado a ser de solo lectura), por lo que debemos encontrar uno diferente para fines de prueba.

Propongamos un ejemplo más orientado a los negocios. Vamos a simular el siguiente escenario:

Si llueve, crea un cupón de descuento "anímate" para tus clientes.

Vamos a utilizar Voucherify, que proporciona una API para crear y rastrear promociones para cualquier sistema de comercio electrónico.

Descargo de responsabilidad: soy cofundador de Voucherify. Estaré encantado de responder a sus preguntas sobre el diseño y la implementación de promociones digitales y, por supuesto, sobre nuestra API .

Ya sabemos cómo conseguirlos del ejemplo anterior, así que centrémonos en crear un bono:

1. Como hemos dicho, siempre debemos comenzar con la documentación.
2. La guía de inicio rápido nos dice que obtengamos nuestra clave API.
   Nota : en lugar de crear una cuenta, puede usar las claves de prueba de la guía de inicio rápido; le mostraremos cómo hacerlo en un minuto.
3. Ahora, veamos cómo crear un cupón de descuento. En Voucherify, este tipo de promoción se representa como “vale”.
4. De los documentos, aprenderá que para crear un cupón, debe llamar a un método POST al punto final de /vouchers .
5. Cree una nueva Solicitud en Postman.
6. Cambie el método a POST.
   

   

7. Pegue el punto final de Voucherify https://api.voucherify.io/v1/vouchers/ y haga clic en Enviar.
   

   

8. Oh, no estamos autorizados a llamar a este terminal. Como habrás adivinado, necesitamos proporcionar claves API.
   
   Voucherify tiene una forma ligeramente diferente de hacerlo. En lugar de ponerlos como parámetros de consulta, debe ponerlos en Encabezados. Este es un enfoque común porque es más fácil implementar y mantener claves de esta manera en lugar de agregarlas como parámetros de consulta.
   
   Agregue las claves como en la imagen y haga clic en Enviar. Tenga en cuenta que Voucherify requiere dos claves. Aquí los que puede usar para este tutorial:
   X-App-Id: 8a824b12-0530-4ef4-9479-d9e9b9930176 X-App-Token: 9e322bac-8297-49f7-94c8-07946724bcbc

   

9. Recibimos otro mensaje de error, esta vez dice que la carga útil no puede estar vacía.
   

   

   
   ¿Qué diablos es una carga útil? Como en el caso de GET queremos recuperar alguna información, con POST necesitamos enviar algo y el mensaje que enviamos se llama payload y normalmente es un archivo JSON.
   
   Ahora la API de Voucherify se queja de que no proporcionamos uno, lo que significa que no puede crear un cupón porque no le dijimos qué tipo de cupón debería crear. ¿Y ahora qué? ¡Volvamos a los documentos!
10. Busquemos qué tipo de información necesita esta solicitud para tener éxito. Podemos ver muchas opciones en la lista.
    

    

    
    Un parámetro (tipo) es obligatorio y otro opcional. Digamos que va a ser un descuento del 20 %, disponible para los primeros 100 clientes, que vence hoy. Ahora necesitamos encontrar los parámetros responsables de estas funciones de descuento y juntarlos en un formato comprensible para la API de Voucherify. Como puede ver en los ejemplos anteriores, la notación JSON que debe usar se ve así:

     { "type":"DISCOUNT_VOUCHER", "discount":{ "percent_off":20.0, "type":"PERCENT" }, "expiration_date":"2018-12-03T23:59:59Z", "redemption":{ "quantity":100 }

11. Para configurar la carga útil en Postman, pegue el mensaje JSON en la pestaña Cuerpo. Seleccione el tipo "sin procesar" y JSON de la lista de formatos de carga útil disponibles y confirme con Enviar.
    

    

12. ¡Voila! Voucherify ha creado nuestro cupón de descuento del 20 % con éxito (como estamos trabajando con una cuenta de prueba, todos los códigos generados comienzan con el prefijo "voucherify.io-"). El equipo de marketing ahora puede compartir el código con los clientes y Voucherify lo validará automáticamente cada vez que vengan a su tienda para canjearlo.
    

    

    
    Pero, ¿cómo sabemos que es una solicitud exitosa? En primer lugar, podemos ver que Voucherify nos ha enviado un mensaje que, según sus documentos, parece una respuesta API correcta. En segundo lugar, Postman muestra el estado 200 OK , lo que significa que nuestra solicitud es exitosa. ¿Por qué 200 y cuál es el estado?

Códigos de estado y mensajes de error de la API

La mayoría de las API con las que interactuará estarán basadas en HTTP. El HTTP es un protocolo que estandariza la comunicación entre varias aplicaciones cliente y servidores en Internet.

Uno de los elementos clave de HTTP son los códigos de estado. Al comprender el código de estado, usted (o en realidad los sistemas que implementa) puede saber de inmediato qué sucedió con su solicitud. Es probable que haya enfrentado uno de los códigos de estado más populares cuando escribió el enlace incorrecto: 404

Pero hay muchos más y los usuarios finales normalmente no los ven. Van desde 100+ a 500+. En general, los números siguen las siguientes reglas:

• 200+ significa que la solicitud se ha realizado correctamente;
• 300+ significa que la solicitud se redirige a otra URL;
• 400+ significa que se ha producido un error que se origina en la aplicación del cliente;
• 500+ significa que se ha producido un error que se origina en el servidor.

Si pudiera seguir los pasos una vez más, vería que Voucherify respondió con 401 No autorizado cuando no proporcionamos claves de API. O 400 Solicitud incorrecta cuando no había carga útil que se requiere para la solicitud Crear cupón. Finalmente, recibimos 200 como muestra de una llamada API exitosa.

Si tiene curiosidad sobre el significado de los códigos de estado HTTP, no hay mejor lugar que HTTP Cats (o tal vez este artículo).

Resumen

La creciente cantidad de datos y la necesidad de velocidad en la creación de productos empujaron a las API a convertirse en la lengua franca de los equipos digitales. Para diseñar sistemas basados ​​en sistemas API-first, asegúrese de comprender las ofertas de los proveedores. Esta guía de prueba práctica es un buen punto de partida para hacerlo. Le ayudará a explorar las capacidades de la API incluso antes de dárselas a su equipo docente, ahorrándoles energía, y también la suya.

Otras lecturas

• “Una introducción a las API de comercio electrónico para personas que no son desarrolladores”, Scott Brinker
• "Vaya más allá del CMS sin cabeza: conozca el comercio sin cabeza", Michal Sedzielewski, Voucherify
• “Cómo usar las plataformas API-First para construir sus sitios web más rápido”, Michal Sedzielewski, Medium
• "Cómo usar su plataforma API-First para preparar su prototipo para la producción", Michal Sedzielewski, Medium
• “Cómo usar la nube para crear aplicaciones más rápido”, Michal Sedzielewski, Hacker Noon