.png){kind=small}
.png){kind=small}
* escrito en colaboración con Pablo Lobo
El Portal del Desarrollador es la puerta de entrada al desarrollador donde tendrá acceso a la documentación necesaria para realizar el consumo de una o más APIs.
Entre sus características se encuentran:
En su estado inicial, cada portal para desarrolladores tiene la marca Sensedia estándar, un usuario super admin y algunas páginas pre-configuradas. Para una mejor presentación y emparejarlo con los sitios web oficiales del cliente, se recomienda que el portal pase por un proceso de personalización, donde se agregue documentación y entradas de API, se realicen configuraciones de restricción de acceso y adaptación a la identidad visual del cliente.
A continuación detallaremos los pasos necesarios para personalizar un portal de desarrollador con el producto Sensedia, mostrando así sus características y posibilidades de configuración y uso:
El término 'documentación técnica' se refiere al archivo que contiene el swagger de una API. El portal tiene una página, llamada API Browser ya pre-configurada para mostrar documentación técnica.
Toda la documentación técnica debe estar disponible en el portal a través de uno de los siguientes 3 métodos:
El término 'documentación funcional' se refiere a toda la documentación que contiene información auxiliar para un swagger de API, como, por ejemplo, una guía de inicio, flujo de autorización, códigos de retorno HTTP, flujos de uso, diagramas, SDK y, si es necesario, enlaces a documentación externa.
Importante: La documentación técnica siempre está asociada a una API específica, sin embargo, la documentación funcional puede referirse tanto a una API específica como a las API de un portal en general.
El encargado de poner a disposición nueva documentación funcional en el portal puede ser alguien del equipo del cliente, preferentemente alguien con conocimientos de desarrollo front-end, o en su defecto, en el caso de clientes que hayan contratado la Developer Experience, donde este profesional pueda hacer que dicha documentación esté disponible en el portal con la ayuda de un analista de UX.
Todas las restricciones y otorgamientos de acceso a los contenidos del portal se realizan a través de un sistema de roles de usuario, los cuales pueden ser asignados a uno o más usuarios para definir sus niveles de acceso a los contenidos del portal. Inicialmente, el portal tiene los siguientes roles de usuario:
Se pueden agregar nuevos roles de usuario según lo requiera cada cliente. Para que se puedan implementar restricciones de acceso, siempre que se agregue un rol de usuario, también se debe agregar un grupo de acceso del mismo nombre asociado a este rol.
Importante: El acceso de usuarios no autorizados a las API, que deben tener restricciones, tiene serias implicaciones de seguridad. Por lo tanto, antes de que cualquier documentación esté disponible en el portal, el cliente debe definir explícitamente las reglas de restricción de acceso.
El término internacionalización (o localización) se refiere a los múltiples idiomas en los que está disponible el contenido. Por defecto, el Portal está disponible en portugués brasileño (pt-br), inglés y español, sin embargo, si lo desea, es posible que esté disponible en otros idiomas de acuerdo con las necesidades de cada cliente.
Además, el propio Portal cuenta con la funcionalidad de traducir un contenido existente, mediante una simple opción en el panel de administrador del mismo mediante la opción traducir.
Importante: La opción de traducción solo está disponible para documentación funcional. En el caso de la documentación técnica, lo ideal es que esté toda en idioma inglés, por razones de buenas prácticas en el desarrollo de APIs.
Para mantener la coherencia visual y coincidir con el manual de marca de cada cliente, el portal debe seguir la identidad visual utilizada en otros sitios y portales de clientes. Toda la personalización visual se realiza a través del archivo Custom CSS.
Al contratar la plataforma, se ofrece a cada cliente una personalización básica que contiene los siguientes elementos:
Para que esta personalización se lleve a cabo, a nivel básico, es necesario que el cliente proporcione una guía de identidad visual o, al menos, la paleta de colores, archivos de tipografía, logotipo e iconos necesarios.
Tras la personalización inicial, cualquier cambio visual posterior es responsabilidad del cliente, o en el caso de clientes que hayan contratado ofertas de Sensedia como Developer Experience o UX Avanzado, este profesional podrá realizar cualquier nuevo cambio visual.
Durante las personalizaciones visuales del portal, los diferentes tipos de archivos deben alojarse preferiblemente en diferentes ubicaciones:
Entonces, ¿está interesado en tener un Portal de Desarrolladores? ¿Está preparado y hacer que esta herramienta esté disponible?
Su uso proporciona una herramienta exclusiva con el objetivo de compartir y difundir la documentación necesaria para el uso de las API, un canal exclusivo y adecuado para la creación y gestión de las APP y enfocado a sus socios, que contiene archivos, documentos y especificaciones para el uso de las API, junto con posibles reglas de uso, SDKs, FAQ y demás información necesaria y pertinente para la comprensión y realización del desarrollo.
Hay que recordar que hemos publicado un artículo exclusivo sobre el Portal de Desarrolladores, donde comentamos la importancia de tener uno, ¡el cual le mostrará los beneficios de usar y apoyar a los desarrolladores!
