.png){kind=small}
.png){kind=small}
* 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:
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:
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:
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.
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:
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.
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.
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:
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:
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!
