¿Qué es una API? Guía Práctica con AWS API Gateway y OpenAPI
API significa interfaz de programación de aplicaciones. Es un conjunto de definiciones y protocolos que se usan para desarrollar e integrar el software de las aplicaciones. Existen varios tipos de protocolos para APIs, el más usado actualmente es REST.
El flujo de una API REST es generalmente como indica el diagrama. El cliente hace una petición hacia la API, esta se comunica con la base de datos o da las instrucciones al servidor para que procese la petición del cliente y la información es devuelta al cliente como respuesta. Para comunicarnos con la api, y así con el servidor, necesitamos hacerlo mediante un lenguaje de intercambio, generalmente JSON o XML.
La API es el intermediario entre la aplicación cliente y el servidor, y como tal, permite identificar a quien hace el llamado, habilitar acceso a recursos y monitorear el tráfico de información. Son reutilizables en varias plataformas y tienen la capacidad de trabajar en el backend y frontend paralela o independientemente. Esto hace que las aplicaciones sean fáciles de escalar, flexibles y fiables.
Impacto de una API
La API está en la mayoría de las interacciones que tenemos con sistemas ya sean públicos o privados. Las organizaciones pueden crear sus propias apis para poder coordinar la información de las distintas secciones de la empresa o del organismo público, empresas dejan sus APIs de manera pública para que cualquiera pueda acceder y propagar su información, otras empresas tienen la API como centro en la disponibilización de sus servicios.
Ventajas de una API
Implementar una API en tu empresa, organismo o aplicación te permite reutilizar funciones en distintos software. Esto disminuye los esfuerzos en el mantenimiento de las aplicaciones y también el time-to-market de tus desarrollos, independientemente de las tecnologías que uses. Te ayuda a monitorear las transacciones de tu empresa para poder tomar mejores decisiones para los proyectos y reaccionar a tiempo en caso de alguna falla. Te facilita los procesos de innovación y transformación de los desarrollos.
La especificación OpenAPI Specification
Existen varias formas de generar el contrato de una API, entre ellas la especificación RAML o API Blueprint. La más usada es OpenAPI 3.0 (OAS3, anteriormente Swagger v2.0), es open-source y usa código JSON o YAML para describir, documentar y consumir APIs. Tiene una estructura modular que facilita la reusabilidad y la cooperación entre desarrolladores.
OAS3 contiene extensiones que permiten conectarnos con otros servicios como ReDoc, APIMatic y Amazon API Gateway.
Aquí te dejo unos ejemplos de código OAS3 y su documentación autogenerada en el editor de swagger.
openapi: 3.0.1
info:
title: Kranio-API
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
tags:
- name: Project
- name: Team
- name: User
- name: options
paths:
/project:
post:
summary: post project
operationId: post-project
tags:
- Project
responses:
200:
description: 200 OK
headers:
Access-Control-Allow-Origin:
schema:
type: string
201:
description: Recurso creado correctamente
headers:
Access-Control-Allow-Origin:
schema:
type: string
...
AWS API Gateway
Es un servicio de Amazon Web Services (AWS) que permite crear, publicar, mantener y asegurar APIs.
La petición del cliente puede ser procesada por aplicaciones privadas, endpoints preexistentes o por otros servicios de AWS como DynamoDB, Kinesis, EC2 entre otros. El más usado es AWS Lambda que ejecuta código sin necesidad de poseer un servidor y soporta distintos lenguajes de programación.
Endpoints
API Gateway describe los endpoints con sus recursos y métodos y cada método se puede integrar y configurar de manera independiente.
Puedes generar los endpoints y sus configuraciones con un archivo OAS3, importandolo en API Gateway con las extensiones necesarias.
paths:
/project:
post:
tags:
- Project
responses:
200:
description: 200 OK
headers:
Access-Control-Allow-Origin:
schema:
type: string
500:
description: Generic Server Error
headers:
Access-Control-Allow-Origin:
schema:
type: string
security:
- api_key: []
x-amazon-apigateway-integration:
type: "mock"
responses:
default:
statusCode: 200
responseParameters:
method.response.header.Access-Control-Allow-Origin: '''*'''
500:
statusCode: 500
responseParameters: method.response.header.Access-Control-Allow-Origin: '''*'''Puedes también describir y configurar estos endpoints a través de la consola de AWS lo que es simple e intuitivo.
Paso 1: Entra al servicio de AWS API Gateway y clickea el botón Crear API, elige crear una API REST (ojo, no la privada) y dale un nombre a la nueva API.
Paso 2: En el dropdown de Acciones elige Crear recurso y dale un nombre. Dentro de este recurso elige desde el mismo dropdown la opción Crear método. Al seleccionar y aceptar el método se presenta la opción de escoger la integración, por ahora selecciona Simulación (mock).
Paso 3: Cuando ya hayas definido todos los recursos y métodos de tu API selecciona la opción Implementar la API (Deploy API) dentro del menú de Acciones. Crea o selecciona una Etapa de Implementación, lo que servirá para ordenar las versiones de la API.
Paso 4: Serás redireccionado a la sección de Etapas donde podrás ver el link para llamar a tu API! Puedes elegir una herramienta como Postman o Insomnia para probar tus endpoints.
Integraciones
En API Gateway existen distintos tipos de integraciones y cada una puede ser proxy o non-proxy. Ambas pueden transformar la petición que viene del cliente pero solo non-proxy puede transformar la respuesta que vuelve del servidor.
Transformar la petición que viene del cliente es útil al momento de integrar dos aplicaciones distintas o pasar parámetros adicionales en el cuerpo o cabecera de la petición.
Transformar la respuesta del servidor es útil para ordenar la respuesta del servidor, agregar cabeceras y modelar según código de respuesta. Es una funcionalidad exclusiva de la integración non-proxy.
AWS API Gateway posee una interfaz gráfica que expresa este flujo y permite configurarlo en 4 etapas.
Solicitud de método: configura la validación de solicitud, método de autorización, uso de API Key y mapeo de parámetros path o query.
Solicitud de integración: configura el tipo de integración, proxy o no y el servicio al que enviará la petición. En el caso de la imagen nos comunicamos con una función lambda de manera proxy. Un ejemplo de código de transformación para mapear el parámetro path en el payload que recibe el backend:
#set($root = $input.params())
{
"pathParameters" : "$root.path.id"
}Respuesta de integración: recibe la respuesta del servidor y puede transformarla. Este ejemplo busca la palabra error en la respuesta del servidor, al encontrarla entonces transforma el código de respuesta a “400”
#set($inputRoot = $input.path('Respuesta de método: proporciona información sobre los tipos de respuesta
La posibilidad de hacer una integración “mock” y tratarla como non proxy ayuda a desacoplar el desarrollo de la aplicación.
Seguridad
API Gateway permite manejar la seguridad de la API de distintas formas.
CORS
Puedes configurar las cabeceras para incluir los parámetros CORS que ayudarán a controlar el origen y los métodos permitidos de las llamadas que se hagan a la API. Esto puede ser descrito en OAS3 o configurado desde la consola en el menú Acciones. Es importante recordar que para habilitar CORS necesitamos tener el método OPTIONS en el recurso. La consola de AWS lo hace por ti pero debes hacerlo para cada recurso en tu API
API Key
Puedes configurar el acceso a tu API mediante API Key. Con ella puedes identificar a quien hace la llamada y restringir el uso de la API mediante quota o throttling.
Para habilitar una API Key necesitas tener un Plan de uso asociado a una Etapa de tu API. Para crearlo vas al menú Planes de uso, presionas el botón Crear y sigues las instrucciones. Al finalizar tendrás una API Key asociada a tu API y será solicitada en la cabecera x-api-key de la petición.
Recuerda que debes habilitar al endpoint para requerir API Key en la Solicitud de método.
AWS IAM
AWS tiene su propio servicio de identificación y permisos llamado AWS IAM. Se rige con el principio de menor privilegio por lo que tiene una forma detallada de dar permisos.
Con IAM te identificas ante la api con las llaves programáticas de tu usuario. Al estar identificado, API Gateway calcula si tu usuario tiene los permisos necesarios para invocar el endpoint.
Autorizadores
Puedes configurar los autorizadores en el menú “Autorizadores” del lado izquierdo y pueden ser de dos tipos:
Lambda Authorizer
Recibe como input un parámetro de la cabecera, generalmente “Authorization”. Este valor es redirigido a una función lambda que discrimina si es o no válido y retorna una política temporal que permite invocar ese endpoint. Podemos usar esta autorización con tokens como JWT o protocolos OAuth o SAML
AWS Cognito
Usa el servicio AWS Cognito para manejar los usuarios, credenciales y permisos custom. Soporta usuarios de identidades federadas como Google, Facebook OpenID Connect entre otros.
Monitoreo
Puedes monitorear tu API Gateway mediante AWS Cloudwatch. Para poder activar el monitoreo debemos asignar el rol correspondiente a la API Gateway en el menú Configuración del lado izquierdo. También es necesario activarlo en el menú Etapas, pestaña Registros/Rastreo. Te recomiendo que selecciones el nivel de registro INFO para obtener un log detallado del flujo de la API Gateway.
AWS Cloudwatch muestra los grupos de log para que puedas debuggear. Puedes usar métricas de API Gateway o crear métricas custom y disponibilizarlas visualmente mediante dashboards. También puedes activar alarmas para notificarte en caso de que alguna métrica supere un límite definido.
Herramientas adicionales
Caché
En el menú Etapas podemos seleccionar si queremos habilitar el caché de API Gateway lo que creará una instancia de caché dedicada. Por defecto y para mayor seguridad, solo se almacenan en caché los métodos GET.
SDK
Cuando tienes la api creada, probada e implementada y quieres usarla en algún proyecto puedes generar un SDK disponible para los lenguajes Java, Android, iOS, JavaScript y Ruby. Úsalos para llamar a tu API desde la aplicación por el lado del cliente.
Créalo en el menú Etapas, pestaña Generación del SDK y escoges el lenguaje de tu preferencia. Apretas el botón Generar SDK para descargarlo listo para usar.
Conclusión
Ahora que sabes lo que es una API, cómo crear, implementar y monitorearla, te invito a usar las herramientas descritas en este post y pensar cómo aprovechar las ventajas de una API para aportar valor a tu negocio, aplicación o proceso de desarrollo.
¿Listo para implementar APIs eficientes y seguras en tu organización?
En Kranio, contamos con expertos en el diseño y desarrollo de APIs utilizando AWS API Gateway y OpenAPI, ayudándote a crear soluciones escalables que impulsan la transformación digital de tu empresa. Contáctanos y descubre cómo podemos colaborar en el éxito de tu negocio.
