Grow your API Management – your way, well documented with DocuPI

Inspiring customers across all channels and at all digital touchpoints is no longer optional, but an indispensable must-have.

With increasing digitalization, application programming interfaces (APIs) are becoming vitally important for connecting the virtual and physical worlds. APIs provide access to a company’s data and make it easily available for customer, partner, and employee interactions. Coleman Parks Research estimated in their studies of 2016 that 88% of large global enterprises are using APIs. In average they were able to reduce their IT costs about 41% and increased their market release speed [1].

In any case, to be used properly, APIs require detailed documentation, an increased level of security, comprehensive testing, routine versioning, and high availability and reliability. Consequently, effective API management is of utmost importance so that developers and companies can secure, control, scale, analyze and, most certainly, monetize APIs. Depending on the size of the company and the use of APIs, API management can include many other tasks and complexities.

Although the topic is often dealt with from a developer’s point of view, it is all the more important for companies to drive API management from a business perspective. Good API management requires an efficient organization with appropriate resources as well as an API portal, also called a developer portal.

For this purpose, there are many providers who, in addition to their gateways, operate complete portals with their own content management systems (CMS), forums, marketing and the like. If you take a closer look at the various offers, you quickly realize that their diversity in terms of content, structure and design is comparable to the plumage of parrots. Some are similar and the next could hardly be more different.

Many companies that are new to the API world want to familiarize themselves with the API topic and then gradually grow into it. A developer portal by the well-known market incumbents, with its abundance of powerful and complex features, can be overwhelming at this point especially for SMEs. More often, a company’s own tech stack is also not directly compatible with that of the solution provider (e.g., CMS which would lead to additional resources for implementation and maintenance). In addition to the questions of how to deal with APIs and which standards should be met, basic foundational tasks such as setup, maintenance, API marketing must also be accounted for.

This way, “a little helper” project quickly becomes a complex endeavor too big to handle. At the same time, a powerful developer portal with probably way too many features would be an overkill for the API solution at this stage.

Therefore, to keep complexity at a minimum, it makes sense to start with an adaptable API documentation portal that grows with the solution.

And this is where one of our real-life client experiences comes into play. For this customer particularly, business analysis and in-depth discussions revealed that an API portal would have been too powerful at that point in time and would have generated more work than value. On top, there was a lack of internal resources for administration and management. In addition, the marketing of APIs, especially for external purposes, had not been fully developed and embraced.

Therefore, we required a lightweight version of an API portal, i.e., a slimmed-down version that is reduced to the essentials. To be precise: an internal overview of APIs with all relevant documentation, which can be managed without a developer. As well as a documentation portal that enabled the separation between technical and business documentation of an API. A later transition to a fully-fledged portal solution was explicitly not ruled out but pushed into the future.

After comparing and analyzing state-of-the-art market offerings, adorsys created different concepts and finally a prototype that incorporated the main requirements.

It quickly became clear to us that for such a documentation portal, the white-label DocuPI solution proved optimal. It enables quick adaptations of content without needing the involvement of developers. And it can be easily integrated into any automated deployment pipeline.

We also hoped that business documentations could mainly be created by product owners based on simple templates. The technical documentation should be reflected in the Swagger file and the content should be managed easily and without releases.

Our white-label solution DocuPI

Key Features of DocuPI:

• documentation portal for APIs
• white-label solution
• separation of business and technical documentation and thus new, but easier to implement standards
• based on Markdown files that can be used without programming knowledge, (e.g., for text adaptations/alterations or to feed in new pages and changes). However, these can be individualized and fine-tuned at any time through the use of HTML.
• semi-automated/container based: Changes in the Markdown file become visible without deployment. This is particularly advantageous for documentation.
• single point of contact for API Management:
  • better overview of existing APIs and planned developments
  • handling of internal standards and requirements such as REST guidelines, onboarding processes
  • contact & support for API Development and Usage

Here is the link to a quick video to give you a better understanding of the tool’s look and feel:

Fully adaptable to your own CI, DocuPI can be used at any company with any design.

Our conclusion: