Introduction

There is no point providing an API if consumers can’t use it, so to make the investment in providing an API worthwhile, it’s incredibly important that APIs are consumable. Part of that can come down to the API Design itself, using existing patterns, having sensibly named paths and operations, using consistent request and response objects and other common API best practices. But what if your API has some special feature or quirk, something that consumers really should know when trying to use it? Or maybe it’s a completely standard API but you just want to provide as much help to your consumers as possible, well there are multiple different ways of doing that, they all have their own strengths and weaknesses, and some will suit some scenarios better than others. But it’s great to have choice, right?

In this post we’ll go through the different options and how they can be used as well as some of the considerations between them.

 
OpenAPI Document
Custom OAI Extensions
Embedded custom documentation pages
Attached files
Developer Portal linked documentation pages
Custom Fields
ExternalDocs

OpenAPI Document

The best way to document an API is within that API document itself. The OpenAPI specification (both v2 and v3) allow the use of Markdown in the description attributes throughout the document. This could be the main API description, operation descriptions, for security schemes, parameters etc. Using markdown allows embedding tables, links to other documentation elsewhere, as well as just making use of formatting, such as different level headings, to make large amounts of documentation easier to read. Code samples can be put in code blocks, so they are styled accordingly and stand out to consumers.

This has the advantage that if the consumer downloads the API document, then they automatically get all the documentation too as it is part of the API.

Examples can also be used as a means of enhancing API documentation. The APIC Developer Portal will generate examples for all parameters, request bodies and responses that conform to the provided schema. It will try and make the example values as appropriate as possible, so for example if a parameter was a string that happened to be named “zipcode” then it will generate a mock US style zip code (e.g., “90210”). If the generated examples are not ideal for your API, then you can embed examples within the API itself using the ‘example’ or ‘examples’ capabilities in the OAI specifications (v2 and 3). In some places, such as parameters there is no example attribute defined in the OAI specification, in those cases if you add an ‘x-example’ attribute then the Developer Portal will honor it. This is an APIC extension to the OAI specification and more information on it can be found in the IBM Documentation.

Custom OAI Extensions

It is possible to add custom extensions to the OAI specification to the API Document. These can be added pretty much anywhere by adding ‘x-‘ attributes. E.g., ‘x-department: loans’. They are simple name/value pairs and will be rendered in the Developer Portal. This can be a simple way of conveying additional information to the consumer to differentiate between different operations or security schemes or just to add additional attributes to the API info object. 

Embedded custom documentation pages

A new feature added to API Connect in 2021 is the ability to embed additional documentation pages within the API document itself. It can even handle a nested hierarchy of documentation pages which will then be displayed in the left-hand navigation menu when viewing the API in the Developer Portal.

These documentation pages are markdown and so can contain rich text such as tables, code samples, formatting etc.

More information on this capability can be found in the IBM Documentation.

The advantage of having the documentation within the API document is that it can be written by the API Developer themselves. It’s as close to the API as its possible to get given it is within the document which should help prevent the documentation and the API getting out of sync. It also means it can easily be stored in change control with your API definitions.

Attached files

Attaching binary files is an option. It can be very useful to attach an SDK zip file for a consumer to download, or if you have existing PDFs of documentation then they can be linked to the API for the consumer to download. Binary files will not be indexed for search on the portal and are not as likely to be indexed by any external search engines such as Google either.

The portal will enforce access control on any attached files. Only users who have access to the API will have access to the attachments on that API.
There is more information on exactly what file types are supported (which can be customised) and how to attach files in the IBM Documentation. 

Developer Portal linked documentation pages

It is possible to create custom documentation pages in the Developer Portal content management system. These pages can be created using the Portal’s WYSIWYG editor and include embedded images, links elsewhere, etc using all the features of the content management system and HTML.

The resulting documentation page (using the “basic page” content type in Drupal) can then be linked to one or more APIs and/or Products. It will then be shown in the left-hand navigation of the API or Product.
If all your APIs use the same security scheme, then this can be a very simple way to provide additional information to the consumer on how to use a specific OAuth flow for instance. The content would only need writing once and then can be set to be shown on every API, including all future ones not yet published.
More information can be found in the IBM Documentation.

Custom Fields

The API Connect Developer Portal is based on a Content Management System and as such the “API” content type can be extended to add additional fields if desired. This is done from the Developer Portal itself and an example of this can be found in the IBM Documentation in the custom sort order tutorial.
Those custom fields can then have a value set by anyone in the Portal with the “Content Author” or “Administrator” role and can be rendered (if desired) in the Portal UI.
The downside of adding extra information this way is that the data is only in the developer portal, it does not flow back to API Manager and is not included in the API Document the consumer downloads from the Portal.

ExternalDocs

External URLs can be linked to from the OAI document using the ‘externalDocs’ feature in the OAI2/3 specification.

The linked file/URL will not be downloaded to the portal and so must be externally accessible, it will also not be indexed for search in the portal.

This is an OAI feature, so it has its place, but it is very much a last resort as it isn’t very feature-rich and is just a way to link to an external website.

Hopefully this has helped outline some of the possibilities in improving the documentation of your API in IBM API Connect.

If you’d like to know more about any of these options, then please post in the comments and we will see if we can help.

#developerportal