En nuestro anterior artículo repasábamos los distintos niveles de visibilidad que puedes asignar a la documentación de tu API para Salud en Nubentos. Pero el API Store de Nubentos ofrece acceso a muchos componentes y facilidades para el consumidor de las APIs. Puede parecer que publicar tu API de Salud Digital en Nubentos supone un problema de seguridad o privacidad para tus recursos.

Nada más lejos de la realidad.

¿QUÉ SE PUBLICA EN NUBENTOS?

Lo primero que conviene aclarar es que tu API no se despliega fuera de tu infraestructura. Si tienes tus recursos en una nube de Amazon, o si los tienes en tu propio Data Center, o en cualquier otra infraestructura propia, publicar tu API en Nubentos es totalmente transparente.

Esto es importante también desde el punto de vista legal. Hay países cuya legislación prohíbe que los procesos sanitarios salgan del territorio.

En Nubentos, únicamente vas a configurar unas URLs, que además no estarán visibles al exterior, y la documentación que quieras incluir. Enseguida veremos que puedes usar la ficha de documentación de tu API en Nubentos para “cerrar la venta”, es decir, conseguir que un visitante anónimo llegue a suscribirse a tu API.

Es muy probable que tengamos que resolver el acceso de Nubentos a tu backend, para que las peticiones que te enviemos desde tus nuevos clientes sean aceptadas por tus sistemas. Habitualmente basta con incluir en nuestra plataforma un mediador que incorpore a la cabecera de la petición las credenciales de acceso, token, claves, etc que generes específicamente para nuestra plataforma.

Aclarado esto, puede que aún tengas dudas sobre la publicación de tu API en un API Store de acceso público, porque podría ser una exposición excesiva. 

En los próximos apartados vamos a despejar estas dudas. Vamos a ver qué puede ver y hacer el consumidor potencial de tu API para Salud en Nubentos, en cada una de las etapas que recorrerá en nuestro API Store: como visitante anónimo, como usuario registrado y como suscriptor de tu API.

CASO DE EJEMPLO: MEDICALAPI

Vamos a usar nuestra API mock de prueba, MedicalAPI, para ilustrar este artículo.

Hemos publicado la API con visibilidad “Pública”, que es la que deben tener todas las APIs que se publican en nuestro API Marketplace.

Hemos añadido además 3 documentos:

• Un documento de bienvenida (“Welcome”), al que hemos asignado el nivel de visibilidad “Same as API visibility”.
• Otro documento de guía (“What can you do”), al que hemos asignado el mismo nivel de visibilidad (“Same as API visibility”). Este documento explica algunos casos de uso básicos de la API, para orientar al potencial consumidor sobre las aplicaciones de la API. Lo hemos publicado en la sección “How to” de la ficha de documentación de la API.
• Otro documento “Agreement requirements”, que contendrá instrucciones detalladas de los requisitos que debe cumplir la empresa que quiere consumir la API (por ejemplo, área geográfica en la que ofrecerá el producto, firma de un acuerdo de licencia, etc.). A este documento le asignamos el nivel de visibilidad “Visible to my Domain”, que indica que solo un usuario registrado en mi API Store podrá ver este documento.

 

Con este planteamiento, vamos a ver qué puede ver y hacer un visitante del API Store de Nubentos con nuestra API MedicalAPI.

VISITANTE ANÓNIMO

Cuando el visitante del API Store público de Nubentos hace clic en el botón “Visit Publisher Store” en la API MedicalAPI, verá el Store privado donde está publicada la API.

 

Sin registrarse ni iniciar sesión en este API Store, esto es lo que verá y podrá hacer cuando haga clic sobre la API:

VISIÓN GENERAL

 

La visión general le permitirá ver las URLs de producción y sandbox de la API y la descripción general de la API que ya estaba visible en el API Store público.

Observa que las URLs que se muestran no son tus URLs originales, sino las que ha generado el Gateway de Nubentos. Internamente resolveremos la entrega de las peticiones a las URLs de tu backend que usaste al publicar tu API.

Observa que no aparece la opción de suscribirse a la API en ningún sitio.

CONSOLA API

 

La pestaña Consola API permitirá al visitante anónimo acceder a la consola de prueba integrada.

El aviso que se muestra aquí es muy importante: el visitante anónimo no podrá probar la API sin el correspondiente Token de Acceso en la cabecera de la petición (“Set Request Header”). Y para ello debe iniciar sesión, y suscribirse a la API.

El visitante sí podrá ver, sin poder usar, todos los recursos que forman la API. Es decir, los métodos que ofrece la API, indicando para cada uno los parámetros de entrada que espera.

 

Es importante tener en cuenta que, en la práctica, esta información tiene poca utilidad sin el Token de Acceso. Desde luego, no supone ningún riesgo para el proveedor de la API. Y al visitante le ofrece una visión muy básica, sobre qué puede esperar de esa API.

Para tener una idea un poco más concreta de la utilidad de la API, lo lógico será consultar su documentación.

DOCUMENTACIÓN

 

Como puede verse en la imagen, el visitante anónimo podrá ver únicamente los documentos con visibilidad pública, es decir, aquellos que se publicaron con nivel de visibilidad “Same as API visibility”.

En este caso están visibles el documento de bienvenida y el de casos de uso principales de la API (que publicamos en la sección “How to”).

El documento de requisitos para el Acuerdo (Agreement requirements), que añadimos con nivel de visibilidad “Visible to my Domain”, no está visible para el visitante anónimo, tal como esperábamos.

SDKs

 

La última pestaña disponible es la que contiene los 10 SDKs que el consumidor de la API podrá usar para integrarla en su software.

El visitante anónimo que trate de descargar un SDK, será conducido a la pantalla de registro. Ningún SDK está disponible para el visitante anónimo. En este punto, esta pantalla es meramente informativa, únicamente muestra los distintos SDK disponibles si decide usar la API.

USUARIO REGISTRADO

Supongamos que el visitante anónimo encuentra interesante la API, y quiere acceder a más información, o quiere suscribirse si encuentra un plan de consumo que le convenga.

Entonces, decide registrarse.

Veamos qué ha cambiado ahora al hacer clic en la API.

VISIÓN GENERAL

 

Lo primero que observamos en la visión general de la API es que ahora nuestro visitante tiene acceso a los distintos niveles de suscripción y tiene la opción de suscribirse a uno de esos planes de consumo.

Para ello deberá seleccionar una aplicación, o usar la aplicación por defecto, y tras seleccionar el nivel de suscripción que le interese, hacer clic en el botón “Suscribirse”.

En nuestra guía rápida para el consumidor de APIs en Nubentos explicamos todo el proceso paso a paso.

Más adelante veremos qué ocurre cuando el usuario se ha suscrito a nuestra API. Ahora sigamos con el usuario que solamente se ha registrado en nuestra API Store.

CONSOLA API

 

En la pestaña que da acceso a nuestra Consola Integrada de Pruebas, Consola API, hay pocos cambios con respecto a un visitante anónimo.

Si observamos, el mensaje de aviso que antes nos decía que debemos iniciar sesión y suscribirnos a la API, ahora nos indica que necesitamos suscribirnos a la API para poder generar el Token de Acceso.

Sigamos con la siguiente pestaña.

DOCUMENTACIÓN

 

En la pestaña de Documentación de la API encontramos ahora acceso al documento “Agreement requirements”, que como recordarás, habíamos publicado en nuestra API con nivel de visibilidad “Visible to my Domain”.

Dado que ahora el visitante es un usuario registrado en nuestro dominio, es decir, nuestra API Store, los documentos publicados con ese nivel de visibilidad son ahora accesibles.

En este caso, como ejemplo, hemos imaginado un documento que informe al potencial consumidor sobre la relación comercial que implica suscribirse a la API y los requisitos que debe cumplir para obtener acceso.

Caben infinitas posibilidades para hacer un uso adecuado de los distintos niveles de visibilidad.

Desde el punto de vista de ventas y marketing, por ejemplo puedes usar el nivel de visitante anónimo para publicar documentación comercial, folletos, casos de éxito, etc, que le puedan convencer para considerar una suscripción.

Aquí, en el nivel de acceso de un usuario registrado, puedes publicar documentación “Visible to my Domain” que contenga información más detallada, aspectos legales, información del proceso de solicitud y aprobación de la suscripción (enseguida hablaremos de esto), etc.

Y en un último paso, con el usuario ya suscrito y por tanto convertido en tu nuevo cliente, puedes intercambiar información más confidencial de manera directa.

Nubentos te ayuda a captar nuevos clientes, pero tu colaboración en el proceso con una gestión óptima de la documentación de tu API, puede resultar clave.

SDKs

 

Visualmente no encontramos cambios en esta pestaña, aparte del bloque de planes de suscripción que aparece siempre para el usuario registrado.

Sin embargo, al hacer clic en uno de los SDKs disponibles, ahora sí se produce la descarga del SDK. En concreto, para el SDK Java se descarga el archivo comprimido “MedicalAPI_1.0.0_java”.

Es muy importante que seamos conscientes de lo que ofrecemos al consumidor de nuestra API al permitirle descargar un SDK.

En primer lugar, tienes que saber que el SDK que se descarga no es el mismo que tú, como proveedor de la API, ofrecerías de forma nativa a tus clientes.

Estos SDKs son generados desde Nubentos. Ofrecen al consumidor la infraestructura de carpetas y archivos necesarios para importarlos en su framework de desarrollo. Incluyen el código generado por nuestra infraestructura y nuestro Gateway para realizar las llamadas a la API y recibir sus respuestas, la gestión de la seguridad y los tokens de acceso, así como los posibles errores devueltos por nuestra plataforma.

No olvides que publicando tu API en Nubentos, somos la fachada de tu backend, y tus nuevos clientes interactúan únicamente con nuestra plataforma. Solo las peticiones correctamente formadas, con el Token de Acceso correcto y que cumplan cualquier otra política establecida en Nubentos, serán pasadas a tu backend.

Y recuerda que el Token de Acceso solo puede generarse si existe una suscripción confirmada para el usuario.

USUARIO SUSCRITO

Pasamos al siguiente nivel de interés. Nuestro visitante anónimo decidió registrarse en tu API Store para saber más sobre tu API y tener la posibilidad de suscribirse a ella para poder usarla.

En este punto, ha decidido suscribirse. Veamos qué ha cambiado ahora.

MÉTODOS DE SUSCRIPCIÓN

Lo primero que debes saber es que en Nubentos existen dos métodos de suscripción, o workflows de suscripción.

 

El workflow básico está activo por defecto cuando un proveedor se une a Nubentos para publicar sus APIs para Salud con nosotros. Es el más directo y el que facilita más una rápida escalabilidad.

Para las empresas que deseen o necesiten tener un control total sobre qué entidad está suscribiéndose a su API, hemos habilitado el workflow avanzado de suscripción.

Este workflow no está activo por defecto, por lo que el proveedor que desee usarlo debe solicitarnos su activación.

CONSOLA API

Sea cual sea el método usado, cuando un nuevo usuario se ha suscrito a nuestra API, la principal diferencia es que dispondrá de un Token de Acceso para Producción y un Token de Acceso para Sandbox.

 

Por tanto ahora ya podrá realizar llamadas a la API.

Para ello deberá seleccionar la Aplicación que le facilita el Token, y el entorno al que enviará las peticiones. Normalmente, será el entorno Sandbox.

En nuestra guía rápida para el Consumidor de APIs explicamos la gestión de las Aplicaciones, las suscripciones y los tokens.

En el resto de apartados de la API no hay cambios para el usuario suscrito.

Pero tener un Token de Acceso le permite ahora completar la integración de la API en su software usando el SDK que quiera, e implementando el código necesario para el uso y renovación del Token.

CONCLUSIONES

En este artículo hemos acompañado a un visitante anónimo al API Store de Nubentos, por las distintas etapas que le conducen hasta su suscripción a una API de Salud disponible en Nubentos.

En cada etapa, hemos revisado qué puede hacer y qué no puede hacer, así como qué puede ver y qué no puede ver.

CONTROL DE DOCUMENTACIÓN

Es importante que el proveedor de APIs conozca bien cómo puede gestionar qué documentos ve el visitante que luego será usuario, para conseguir que se convierta en cliente al suscribirse a su API.

La documentación puede organizarla en distintos niveles de visibilidad, y si activa la suscripción avanzada puede dejar la información más sensible para cuando apruebe la suscripción y resuelva los términos contractuales con su nuevo cliente.

SUSCRIPCIÓN AVANZADA DISPONIBLE

También es importante que conozca que existen dos métodos de suscripción, uno básico, en el que la suscripción es inmediata, y otro avanzado, en el que el suscriptor queda a la espera de que el proveedor apruebe o rechace la suscripción.

Este workflow avanzado debe ser activado a petición del proveedor para, además de controlar qué entidades se suscriben a su API, completar los detalles contractuales o legales que crea conveniente con el potencial cliente, antes de aprobar su suscripción.

SDK PARA EL GATEWAY DE NUBENTOS

Otro detalle importante es que el proveedor de APIs en Nubentos puede estar tranquilo en cuanto a la visibilidad de sus recursos.

Los recursos técnicos están a salvo en todo momento, puesto que los SDK que ofrece Nubentos incluyen únicamente el código necesario para interactuar con nuestra plataforma Gateway y poder gestionar las peticiones, respuestas y errores con su API.

RESTRICCIÓN MÁXIMA PARA LOS TOKENS DE ACCESO

El usuario no podrá realizar ninguna invocación, ni en producción ni en sandbox, ni desde su software ni en nuestra Consola Integrada de Pruebas, mientras no tenga los correspondientes Tokens de Acceso.

Los Tokens se generan a nivel de Aplicación y sólo para usuarios suscritos a la API.