Blog

Cómo gestionar la visibilidad de la documentación de mi API en Nubentos

por | 14 Oct 2019 | 0 Comentarios

por | Oct 14, 2019 | Howtos | 0 Comentarios

Proteger tu API para Sanidad no solo consiste en implementar los controles de autorización y acceso a la API, sino también en gestionar adecuadamente la visibilidad de su documentación.

Puede que al público en general le resulte interesante conocer una descripción de la funcionalidad que implementa la API y algunos criterios de prestación de servicio, como puede ser su rendimiento, el SLA, sus principales casos de uso o la cantidad de empresas que hacen uso de ella.

Pero quizás sería conveniente que los detalles relativos a los precios por uso y las condiciones de contratación sólo estuvieran disponibles para usuarios registrados.

Y por último los detalles sobre cómo usar la API o los aspectos técnicos de sus métodos, respuestas, etc. solo deberían estar disponibles para usuarios suscritos a la API.

Como vemos existen diferentes niveles de acceso a la documentación que debemos tener presentes en nuestra estrategia de APIs para Sanidad. 

En este artículo vamos a tratar cada uno de los privilegios que se pueden asignar a los documentos que acompañan a las APIs publicadas en Nubentos y la relación que tienen con el grado de visibilidad de la API. 

Niveles de visibilidad a nivel de API

Comencemos por hacer un repaso de los distintos niveles de publicación que tiene una API.

Imaginemos que vemos un producto en el escaparate de una tienda. Junto a él hay una descripción que detalla algunos de los aspectos y funcionalidades del producto. En este caso el producto está expuesto al Público y es por definición el estado en el que debemos publicar nuestra API para que todos los usuarios puedan conocerla. 

Esto se hace por defecto cuando estamos editando la API, y se informa en la primera fase de la creación de la misma.

API Public nubentos

Si esa información y el producto nos resulta interesante entramos a la tienda y solicitamos más información.

Si somos de confianza el encargado estará encantado de dejarnos ver el producto y explicarnos su funcionamiento, dejarnos ver sus características, revisar la garantía y las condiciones de venta del mismo. 

De forma similar si tenemos acceso al espacio donde está publicada una API pública podremos ver mayor detalle de la misma, realizar peticiones desde la consola o acceder a documentación que de otro modo no veríamos. 

Pero imaginemos que, por la razón que sea, el vendedor no quiere exponerlo al público, y solo los compradores que entren en la tienda pueden verlo y decidir si lo compran.

Pensemos por ejemplo en un conjunto de APIs que trabajan juntas, pero una de ellas es la API principal. Quizás no tenga sentido que todas estén visibles públicamente, sino que, cuando el cliente se registre en el Store correspondiente, pueda ver el resto de APIs adicionales, de uso opcional para un determinado caso de uso. 

En este caso en vez de elegir que la visibilidad de la API sea “Public” debemos elegir la opción “Visible to my domain”. De este modo un usuario que no se haya registrado como consumidor de la API no podrá ver nada de la misma.

API Visible in domain nubentos

Con esto tenemos definidos los dos posibles niveles de visibilidad que podemos elegir cuando publicamos una API. Recordemos que, salvo casos muy especiales, debemos establecer su visibilidad como Public

¿Qué relación tiene la documentación con la publicación de la API?

Es lógico pensar que al estar la documentación asociada a la API, la documentación tendrá la misma visibilidad que se asocia a la API al publicarla.

Pero la plataforma nos da más opciones. 

Cada documento o recurso documental puede tener una visibilidad al menos tan restringida como la de la API. 

Existen tres niveles de visibilidad para cada recurso documental. 

1.- “Same as API visibility”: De modo que si cambiamos la API de pública a restringida por dominio todos los documentos que tengan activada esta opción pasarán a tener la misma visibilidad. Es interesante que la información de marketing, características y funcionalidades que le dan la entidad a la API tengan asociada esta visibilidad.

2.- “Visible to my Domain”: En este caso aunque la API sea pública solo los usuarios registrados podrán acceder a estos documentos. Es una opción ideal para información técnica detallada de la API o relativa a aspectos legales. 

3.- “Private”: Esta documentación sólo está disponible para los perfiles desarrolladores y consultores que acceden al portal de publicación. Podemos agregar unas instrucciones para miembros de nuestro equipo o relativas al roadmap de nuestra API, o una lista de errores conocidos para que otro técnico de nuestra organización conozca las peculiaridades de la API publicada.

¿Cómo hago para cambiar entre los tres tipos de visibilidad de la documentación? 

Pues para ello por cada recurso de documentación que vamos a publicar seleccionaremos el adecuado en el campo “Visibility” como se muestra en la siguiente animación:

Doc Visibility nubentos

En la vista de documentación podemos ver qué visibilidad tiene cada uno de los documentos para asegurarnos que está correctos.

Doc Resume nubentos

 En la siguiente animación vemos como quedaría la visibilidad de los documentos si la API está como pública.

Doc View nubentos

En la animación podemos observar como si no accedemos con usuario y contraseña tan solo aparece un documento asociado a la API (“Same as API visibility”), mientras que tras hacer login podemos acceder al resto de los documentos (“Visible to my domain”).

Conclusiones

Determinar la visibilidad de los recursos documentales de nuestra API es tan importante como el contenido de los mismos y determinará el grado de satisfacción de nuestros posibles clientes.

Debemos hacer una balance entre mostrar información poco relevante para los desarrolladores o responsables de TI que se acerquen a nuestro “escaparate” para ver las APIs disponibles y agregar recursos de valor añadido para nuestro clientes confirmados, como pueden ser acceso a foros privados o a desarrolladores de nuestra organización que puedan apoyarlos en el proceso de integración.

Es muy importante mantener de forma coherente la protección en el acceso a nuestra API y a su documentación.

En Nubentos puedes gestionar la visibilidad de la documentación que acompaña a tu API con distintos niveles, para distintos contenidos.

Si quieres saber más sobre los procesos de trabajo de Nubentos, encontrarás más vídeos explicativos en nuestro canal de Youtube.

0 comentarios

Enviar un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Your competitors know, don’t be left out.

Receive in your mail all the news about Nubentos: articles, eBooks, new APIs, interviews, guides, etc. in our Newsletter with the best of each month.