API Portal

An API portal is a type of specialist documentation platform that focuses on documenting distributed and local APIs. Although this is a subcategory of ‘platforms’, many applications in this category simply produce HTML files which can be hosted using any web server, which is convenient for DocOps purposes.

This is an non-exhaustive list of examples, by category:

• Distributed APIs (i.e., web services)
  • SwaggerHub - REST APIs based on the OpenAPI Spec.
  • GraphQL Playground - GraphQL
  • Microsoft API Management Developer Portal - REST APIs, SOAP, GraphQL, etc.
• Local APIs
  • Doxygen - Most popular programming languages including C, C++, Python, Java, C#, PHP, and more.
  • Sphinx - Primarily Python and C++ with extensions for others.
  • JavaDoc - Java’s own documentation generator.
  • DocFX - Open source documentation generator for C# projects.

DocOps Automation

Most generators for local APIs are DocOps-friendly in the sense that they produce HTML files that can be easily parsed and integrated with the main documentation platform. Likewise, the underlying templates can also be customized so that they appear like first-class citizens within the documentation system.

Portals for distributed APIs, instead, usually come with their own web server and may not generate static HTML. Although most allow customization to match are approximate the main documentation platform’s theme, the user experience is most prescriptive, according to how the vendor believes APIs are best documented. Having said this, most such tools provide interactive sandboxes, and real-time generation of example code in different languages, which compensate for any shortcomings in DocOps automation.

Limitations

API portals are essentially for reference-level documentation. They are not substitutes for ‘getting started’ guides, tutorials, and so on. The biggest inadvertent limitation, though, is that they are not full fledged developer portals. They are silent on what microservices host each API, what hops a request goes through (DNS, DDoS, API Gateway, Kubernetes Service, etc.), what databases the microservice connects to, and so on. An API portal is an important but small piece within an enterprise’s documentation system.