Una introducción sencilla para trabajar con API

Llamada API típica

Si trabaja cerca de la industria del desarrollo web, seguramente escuchará estas tres infames cartas: A. P. I.

Tanto los principiantes como los expertos los arrojan:

"¿Por qué tengo que hacer una llamada API? ¿Tiene un número?

"Una simple llamada a esta API de terceros hará el truco aquí".

"Le crearemos una API RESTful; asegurándose de que su nuevo sistema funcione bien con otros servicios ".

Si bien las API pueden parecer primero intimidantes, literalmente pueden cambiar su vida como desarrollador.

¿Por qué? Bueno, aprender a usar las API correctamente puede simplificar, acelerar y fortalecer su flujo de trabajo de desarrollo. La creación o integración de API brinda beneficios tanto para los clientes como para usted.

Como desarrolladores, a menudo escuchas el consejo: "no reinventes la rueda".

Bromas aparte, las API juegan un papel importante en no reinventar la rueda. Comprender los conceptos básicos de las API es una habilidad crucial para los desarrolladores web modernos. En esta publicación, te ayudaré a hacer exactamente eso. Cubriremos:

  • Los beneficios de usar una API
  • Qué es realmente una API
  • ¿Qué tipos de API hay?
  • Casos de uso practico

Vamos a sumergirnos en eso, ¿de acuerdo?

¿Por qué usar APIs?

Mejora tus habilidades de desarrollo con API

Uno de los primeros hitos importantes en mi carrera de programación fue comprender las API correctamente. Todavía los uso todos los días.

Antes de entrar en el meollo de la cuestión, permíteme convencerte primero de que vale la pena entender las API. ¿Cómo es eso?

Porque aprender a usar API aumenta dramáticamente la efectividad de su desarrollo.

Primero, le permite aprovechar la lógica preexistente que no tiene que escribir. ¡Algunas cosas que tal vez no puedas codificar! Para ahorrar un tiempo precioso como desarrollador, es importante tener una idea de cómo se ve el panorama API.

En segundo lugar, muchos problemas de desarrollo que encontrará ya han sido resueltos por alguien antes que usted.

Estas soluciones existentes podrían ser FaaS, bibliotecas, servicios web, SDK, API de contenido. Cualquiera sea la forma que adopten, lo más probable es que necesite una API para interactuar con ellos.

¿Qué son exactamente las API?

API web, imagen de MS

La definición oficial (desalentadora) es la siguiente:

En la programación de computadoras, una interfaz de programación de aplicaciones (API) es un conjunto de definiciones de subrutinas, protocolos y herramientas para construir software de aplicaciones. En términos generales, es un conjunto de métodos de comunicación claramente definidos entre varios componentes de software. Una buena API facilita el desarrollo de un programa informático al proporcionar todos los bloques de construcción, que luego el programador reúne.

Un poco pesado, ¿eh? Llevemos la prosa académica a un nivel inferior. Aquí hay una definición API más amigable y casera:

En pocas palabras, una API declara una interfaz para que pueda interactuar con su lógica sin necesidad de saber qué sucede debajo del capó. Esta definición se aplica a cualquier idioma, protocolo o entorno en el que se encuentre. El único requisito es que ocurra en el nivel programático. Más sobre eso a continuación.

Para arrojar una luz aún mejor sobre las API, enumeremos lo que NO son:

  • Una API no es necesariamente un servicio externo. Por ejemplo, puede incluir bibliotecas directamente en su solución O usarlas a través de una API.
  • Una API no es solo una interfaz. Es tanto la especificación / formato como la implementación.
  • Una API no es una GUI (interfaz gráfica de usuario). Una API no hace interacciones en el nivel gráfico. Solo opera en la capa programática. Esto puede ser a través de un lenguaje de programación o un protocolo de comunicación.

Diferentes tipos de API

No todas las API son iguales.

Aunque en su mayoría comparten el mismo objetivo, algunos lo logran mucho mejor que otros. Como se trata de una introducción sencilla, no voy a profundizar en lo que hace que una API sea mejor que otras.

Tenga en cuenta que las personas tienen enfoques realmente diferentes para crear API. Si ese tema le interesa, busque en Google "patrones de diseño de API" y "paradigmas de API". O simplemente comience con este interesante artículo de nivel de entrada. :)

Puntos finales

El objetivo de las API es facilitarle la vida como desarrollador. ¿Cómo lo hacen?

Al agregar características / funciones establecidas y exponer estas funcionalidades a través de puntos finales. Estos son típicamente patrones de URL utilizados para comunicarse con la API.

Estos puntos finales son la única forma en que puede interactuar con cualquier API. Cada punto final tendrá un formato específico tanto para sus solicitudes como para sus respuestas. Por lo general, encontrará este formato definido en la documentación de la API.

Los puntos finales pueden ser funciones simples. O bien, pueden estar compuestos de muchas funciones, que pueden llamar a otras API, etc.

El punto crucial aquí es que la lógica subyacente de esas funciones está completamente abstraída. No necesita ningún conocimiento de lo que sucede dentro de ellos para usarlos.

Mientras utilice el formato adecuado, podrá consumirlos. Aquí, "consumir" es una manera elegante de decir "usar partes de ellos para su aplicación".

La conclusión es esta: una API es como cualquier interfaz.

En comparación, un interruptor de luz encenderá una luz, ya sea que sepa cómo funcionan o no las corrientes eléctricas. (Como adulto joven, también aprendí que debes pagar la factura de la electricidad para que funcione ... pero esa es una historia diferente ...)

Cómo usar las API: ejemplos prácticos

Cambiemos la teoría por alguna práctica fácil ahora.

Lectura de documentación de API

No quiero extender demasiado las explicaciones conceptuales. En cambio, analicemos una API realmente sencilla. Veremos cómo funciona en un escenario de la vida real. Usaremos el objeto nativo de JavaScript Math para hacer esto. Puedes leer su documentación aquí.

Los documentos explican cómo cada función del objeto Math describe cuál debería ser el formato de entrada. Por ejemplo, podría ser un número o una matriz de números.

Los documentos también describen el formato de la salida.

Observe cómo no se menciona nada sobre la lógica utilizada para ejecutar estas funciones.

Por ejemplo, si enciende la consola de su navegador y escribe Math.sqrt (sin ejecutar la función), verá algo como:

ƒ sqrt () {[código nativo]}

Ese es el espíritu de una API. Ya sea que llame a una de las API de su sistema operativo o a una API basada en la web, estos principios se mantendrán.

Ejemplos básicos de casos de uso de API

Hay un montón de cosas que se pueden hacer con proveedores de API populares.

La API de Google Maps a menudo se usa para crear mejores experiencias de usuario con datos basados ​​en mapas en tiempo real y señales de tráfico. La API de Twitter se puede utilizar para filtrar y mostrar Tweets específicos en tiempo real.

Ahora, sospecho que muchos de ustedes están más interesados ​​en las API basadas en la web que cualquier otra cosa. Así que vamos a sumergirnos en casos de uso específicos.

Usaremos Postman en nuestros ejemplos. Este Rest Client está vinculado a un entorno web, pero estas herramientas generalmente también existen en otros entornos. Vale la pena echar un vistazo a las herramientas proporcionadas para un entorno determinado antes de comenzar a jugar con ellas. Esto puede ahorrarle mucho tiempo.

Si desea seguirlo, deberá descargar el cliente Postman.

Consumir una API pública para obtener datos

Nuestro primer ejemplo será bastante simple, pero aún más interesante que el de Matemáticas.

¡Usaremos la API de perro!

No solo es una API divertida, sino que tampoco requiere ninguna autenticación.

Además, es una API REST de HTTP. Esto significa que es una API basada en la web. Dado que está vinculado a este entorno, requiere que cumplamos con algunas de las especificidades del protocolo.

En este caso, esto significa usar verbos HTTP como GET, PUT, POST, DELETE.

Para nuestro ejemplo, mantendremos las cosas simples y solo usaremos el verbo GET. La API no admite nada más de todos modos. La mayoría de las API públicas solo le permiten consumir datos y no publicar ninguno.

Pongamos en marcha Postman y veamos cómo se ve su interfaz de usuario.

Mi interfaz de usuario usa el tema oscuro, por lo que puede diferir ligeramente del tuyo.

Puede haber mucha información para digerir al principio aquí, así que comencemos con el VERBO y la URL.

El verbo predeterminado debería ser GET. Si es así, puede mantenerlo de esta manera e ingresar la siguiente URL: https://dog.ceo/api/breeds/list/all

¡Haz clic en "Enviar" y explota! Debería recibir una respuesta con los datos apropiados. Voilà! Acaba de hacer su primera llamada a la API.

Ahora, para este ejemplo, no utilizaremos ninguno de los datos recibidos. Pero se entiende la idea. Puede mostrar diferentes razas de perros a su usuario y mostrar una imagen de una raza determinada si hace clic en ella.

Puedes jugar con las diferentes rutas en su documentación para familiarizarte con el entorno.

Dato curioso: este pequeño proyecto también es de código abierto, por lo que puede echar un vistazo aquí.

Manejo de autenticación con una API privada

Con suerte, ahora comprenderá mejor cómo funcionan las diferentes piezas juntas cuando se trata de API. Hagamos un tutorial más complejo que incluya autenticación. Voy a utilizar una de mis "aplicaciones propias" API aquí.

Aquí solo usaremos código para interactuar con la API de Snipcart. Puedes cerrar Postman, pero tenlo a mano. Es bueno usar una herramienta de este tipo al comenzar con una API.

El objetivo será crear una herramienta de interfaz de línea de comando (CLI) simple para crear descuentos de uso por única vez para los compradores. Estos descuentos se generarán a través de una API. Todo esto sucederá completamente en su computadora.

Crea una nueva carpeta para este proyecto. Use npm init en la carpeta y arranque su editor de texto.

Ahora cree un archivo index.js, luego abra el archivo package.json. En él, agregue las siguientes líneas en el objeto de nivel superior:

"bin": {"discount": "./index.js"}

También necesitaremos el paquete commander para analizar las entradas del cliente. Ejecute npm install --save commander en la carpeta actual.

También usaremos una pequeña lib para crear ID. Puede instalarlo con npm install --save shortid.

Mientras lo hacemos, ejecutemos también npm install --save request lib. Esto nos facilitará hacer llamadas HTTP. Regrese a su archivo index.js y pegue este código:

Centrémonos solo en la función de solicitud aquí.

Aquí es donde hacemos la llamada API externa a Snipcart. Puedes ver que pasamos el método: "POST" al método. Esto se debe a que queremos PUBLICAR datos en la API de Snipcart. Al especificar este método, la API asignará la acción correctamente. Esto le permite leer el cuerpo de la solicitud donde se encuentran los datos de descuento.

Una característica interesante de la API que aún no hemos utilizado es la autenticación.

Nuestros otros ejemplos fueron todos en API públicas. Estos no requieren autenticación.

Pero en la vida real, la mayoría de las API que usará probablemente requerirán alguna autenticación. Es un "patrón" estándar en el mundo API. ¡Nuestros clientes no estarían contentos si permitiéramos a alguien crear descuentos en su tienda! ;)

Para nuestro propósito, pasamos la clave API directamente en la solicitud.

¡Hurra, el servidor nos reconoce! Luego puede ejecutar la solicitud con un alcance solo para nuestra cuenta.

Si desea probar nuestra pequeña aplicación, puede ejecutar npm install -g en el directorio del proyecto. Luego, simplemente ejecute descuentos x para crear descuentos x número de veces.

Puede ir a su tablero de Snipcart (cuentas gratuitas para siempre en modo Prueba) y comprobar por sí mismo que los descuentos se han creado correctamente.

Puedes imaginar lo poderoso que puede ser esto. Si tuviera que crear 200 de esos descuentos, esto requeriría mucho tiempo para hacerlo a través de nuestra interfaz de usuario.

Cuando esté familiarizado con el funcionamiento de las API, esto se puede hacer en cuestión de minutos. El código también es reutilizable, así que si necesita hacerlo lo mismo dentro de un mes, bueno ... ¡ya está configurado!

Pensamientos finales

Realmente espero que este manual le haya ayudado a comprender mejor qué son las API y cómo puede aprovecharlas en su flujo de trabajo de desarrollo.

Algunas conclusiones:

  • Las API acelerarán su velocidad y ampliarán su alcance de desarrollo. ¡Usalos, usalos a ellos!
  • Las API NO están necesariamente vinculadas al ecosistema web. Los verás en todas partes.
  • Siempre revise la documentación de la API que desea usar.
  • Siempre busque herramientas existentes (API o de otro tipo) en su ecosistema antes de comenzar a codificar.

Nuestro último ejemplo no está realmente listo para "producción". Pero le da una buena idea de cómo se verían las cosas en un caso de uso de la vida real.

Hay muchas cosas que podríamos haber mejorado. Por ejemplo:

  • Permitir al usuario elegir el tipo de descuento
  • También podríamos enviar los códigos creados por correo electrónico directamente en la misma función, en lugar de simplemente registrarlos.
  • Si tuviéramos necesidades avanzadas para nuestras herramientas de descuentos, podríamos haber escrito una API nosotros mismos. A partir de ahí, incluso podríamos crear una interfaz de usuario que interactúe con nuestra API si quisiéramos. De todos modos, espero que te hagas una idea ahora. :)

Entonces, ¿cuál es el siguiente paso? Como casi cualquier cosa en la esfera del desarrollo, ¡necesitará codificar, codificar, codificar y codificar un poco más! Así es como se familiarizará con la administración e integración de API.

Después de un tiempo, serás eficiente con ellos.

Y ahí es donde comienza la verdadera diversión.

Si te ha gustado esta publicación, tómate un segundo para aplaudir y compartirla en Twitter. ¿Tienes comentarios, preguntas? ¡Haz clic en la sección de abajo!

Originalmente publiqué esto en el blog Snipcart y lo compartí en nuestro boletín.