Articles
5
min of reading
March 8, 2022

Learn more about the Sensedia Developers Portal

Luciana Bandeira
Developer Experience
I help developers with onboarding and API best practices to ensure the best Developer Experience. In my spare time I dedicate myself to books, researching (and tasting) desserts and I'm passionate about travelling.
More about the author

* written in partnership with Pablo Lobo


The Developer Portal is the developer's gateway where they will have access to the documentation needed to perform the consumption of one or more APIs. 

Among its features are: 

  • exposure of technical documentation of APIs (swagger); 
  • exposure of functional documentation; 
  • generation and management of credentials necessary for consuming APIs;
  • consultation of dashboards containing information regarding APIs;
  • consult the most frequently asked questions and answers from other developers
  • important links to development-related documentation and best practices
  • service channels, if applicable to the customer.

In its initial state, every developer portal has the standard Sensedia branding, a super admin user and a few pre-configured pages. For a better presentation and to pair it with the client's official websites, it is recommended that the portal go through a customisation process, where documentation and API inputs are added, access restriction settings and adaptation to the visual identity of the client.

Below we will detail the steps necessary to customise a developer portal with the Sensedia product, thus displaying its features and configuration and use possibilities:

Technical Documentation

The term 'technical documentation' refers to the file containing the swagger of an API. The portal has a page, called API Browser, already pre-configured for displaying technical documentation.

All technical documentation must be made available on the portal through one of the following 3 methods:

  • Brought from API Platform using the “show iterative documentation (swagger)” option.
  • Uploading directly through the portal, through the Swagger 3 screen. Through this method it is possible to carry out access restrictions according to roles/profiles.
  • Using a page with the previously configured Redocly library.

Functional Documentation

The term 'functional documentation' refers to all documentation containing auxiliary information for an API swagger, such as, for example, a getting started guide, authorisation flow, HTTP return codes, usage flows, diagrams, SDKs and, if necessary, links to external documentation.

Important: Technical documentation is always associated with a specific API, however, functional documentation can either refer to a specific API or the APIs of a portal in general.

The person in charge of making new functional documentation available on the portal can be someone from the customer's team, preferably someone with knowledge of front-end development, or, alternatively, in the case of customers who have contracted the Developer Experience, where this professional can make such documentation available on the portal with the help of a UX analyst.

Access Restrictions

All restrictions and grants of access to portal contents are made through a system of user roles, which can be assigned to one or more users to define their levels of access to portal contents. Initially, the portal has the following user roles:

  • Anonymous user: any user who is not logged into the portal.
  • Authenticated user: a user who is registered and logged into the portal.
  • Administrator: a user with portal administration privileges.

New user roles can be added as required by each customer. So that access restrictions can be implemented, whenever a user role is added, an access group with the same name associated with this role must also be added.

Important: unauthorised user access to APIs that should be restricted has serious security implications. Therefore, before any documentation is made available on the portal, access restriction rules must be explicitly defined by the customer.

Internationalisation

The term internationalisation (or localisation) refers to the multiple languages in which content is available. By default, the Portal is made available in Brazilian Portuguese (pt-br), English and Spanish, however, if desired, it is possible to make it available in other languages according to the needs of each client.

In addition, the Portal itself has the functionality of translating existing content, using a simple option in the administrator panel of same by selecting the option translate.

Important: the translation option is only available for functional documentation. In the case of technical documentation, it is ideal for them all to be in English, for reasons of good practices in the development of APIs. 

Visual Customisations

To maintain visual coherence and match each client's brand manual, the portal must follow the visual identity used on other client sites and portals. All visual customisation is performed through the Custom CSS file.

Upon contracting the platform, basic customisation is offered to every customer, containing the following elements:

  • Colour palette.
  • Typography (font, size, weight and colour of texts and titles).
  • Logo change.
  • Icon change.
  • Adequacy of the portal home page.

For this customisation to be carried out, at a basic level, it is necessary for the client to provide a visual identity guide or, at least, the colour palette, the necessary font, logo and icon files.

After the initial customisation, any subsequent visual changes are the responsibility of the customer, or, in the case of customers who have contracted Sensedia offers as a Developer Experience or Advanced UX, this professional may make any new visual changes.

During the visual customisations of the portal, different types of files should preferably be hosted in different locations:

  • Font files must be used through a CDN or hosted in the portal's file browser.
  • Image files, including logos and icons, must be hosted in the portal's file browser.
  • Video files must be hosted externally on a video streaming service.

So, are you interested in owning a Developers Portal? Are you prepared and make this tool available?

Its use provides an exclusive tool with the aim of sharing and disseminating the necessary documentation for the use of APIs, an exclusive and suitable channel for creating and managing APPs and focusing on its partners, containing files, documents and specifications for the use of APIs, along with possible usage rules, SDKs, FAQs and other necessary and pertinent information for understanding and carrying out the development.

A reminder that we have published an article exclusively about the Developers Portal where we comment on the importance of having one. It will show you the benefits of using and supporting developers!


Thanks for reading!