This talk was presented at API The Docs Virtual 2022 event series on 21 September. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit the talk listing page for an overview of all presentations!
Christoph Weber
Solutions Architect at Pronovix
Christoph's presentation (video recording)
Christoph's slides
Q&A
- What is the question that clients with a complex API set you wish they asked you earlier?
- APIs can be used from almost any programming language. How do you handle providing examples that satisfy the widest programming audience? Is it worth having examples for every language?
- Do you try to make different API’s documentations consistent in tones and structures or each API documentation has its own needs so that wouldn’t really make sense?
- On your site, do you have cases of developers that use more than one API or each API has it’s own separate set of developers?
Read Christoph's article One Developer Portal To Document Them All.
”It’s all about the journey, the developer’s satisfaction. Are they finding what they need? Can they be successful? Are they sticking with you? That’s really the big goal.”
In the presentation, you can hear about:
- What are the reasons that APIs in modern enterprises are rarely uniform?
- Why is it important to have an appealing, clear documentation on API references?
- How can the different types of APIs be documented properly?
APIs at modern enterprises
- Organic growth: different business units start different methods, which can lead to a wide variety of API solutions.
- Mergers and Acquisitions: they bring in different approaches to the same overall goal, which results in a non-uniform API landscape.
- Specifical Technical Needs: there can be large differences between the customers’ needs.
- Any other reasons that we are not fully or even partly aware of.
The result
The result of all of these factors, that we may have…
- REST API with their specification,
- Async API with their specification,
- SOAP API with their specification,
- GraphQL API with their documentation,
- gRPC API with their documentation,
and there can possibly be additional types of API specifications and documentations as well.
The goal
Pronovix’ main purpose is to have all of this in one developer portal rendered properly, with additional documentation for each API type, in a sort of uniform way to facilitate developers’ journey.
“Once a company decides to fully manage and document their APIs, put emphasis on an API-first strategy, and streamline digital governance, they start looking for a developer portal that can support their needs and really document the artifacts they have.”
API documentation at Pronovix’ developer portals
- Themed Swagger UIs to make the website visually more appealing.
- Multiple tabs for different types of APIs.
- API descriptions on the landing page to give a quick look of the meaning of the APIs and helps to decide, which one fits the most for the developer’s goal.
- Descriptions on business purposes of the APIs.
- Having a full set of information under one roof about the APIs to facilitate the way of learning the details and seeing the big picture.
- Knowing the needs of the developers’, what are they familiar with in different specifications of APIs.
Conclusion
A large variety of API types and protocols can be documented in a single, cohesive developer portal in a straightforward and visually appealing way.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.
