Interface Completeness

Poor documentation is one of the most frequent problems faced by API consumers. For example, resources often have no description showing us what they’re for and requests often fail without the return telling us what we should do to get the call through. Problems of this type can be avoided if there’s governance in place establishing that APIs can only be deployed in a production environment if their documentation is ok.

Sensedia developed the Interface Completeness feature precisely to help you visualize how complete an API’s documentation is.

There’s no specific screen for Interface Completeness within Sensedia Adaptive Governance. The feature is available in the upper right corner of the Overview screen of an API on Sensedia API Platform:

The feature analyzes the API’s Swagger and compares the amount of fields it has with the total amount of fields that could be included in a Swagger file. Based on this comparison, it shows a percentage to represent the file’s completeness degree. Also, based on the problems detected, it offers suggestions so you can improve the documentation (read more about it below).

With this, you can:

use the completeness percentage as a requirement to promove APIs from one workflow stage to another (see more about it below);
ensure that the API you’re exposing to the public on your Developer’s Portal is sufficiently documented (you can choose to expose APIs on the Developer’s Portal on the API’s Overview screen on Sensedia API Platform).

How can I interpret the Interface Completeness percentage?

To get to the final percentage, we compare the quantity of fields your Swagger file has to the total quantity of fields that could be included. Using our expertise on APIs, we assign different weights to the fields, to value items that are more important (for example, including HTTP return codes is more important than describing the error). We also validate the format of some fields, for example:

descriptions must have a minimum length and can’t be sequences like ABC or 123;
the API’s base path should include the API’s name and version, and they should match the name and version registered.

Anyway, the final result is quantitative not qualitative: it provides a measure of documentation completeness, it says nothing of the quality of the design. For example, we check whether your API has a description, not whether the description is well suited to what the API does or whether it is clear to the consumer. You can and should use this percentage as a checkbox before exposing the API, ensuring that the Swagger has been worked on and is sufficiently complete, but not as a validation of the API’s quality.

As to the percentage value that could work as a completeness threshold, this depends on your API strategy and the objectives of each API you design. That’s why you can define any value you want for Interface Completeness as a requirement to promote APIs from one workflow stage to another (see more about it below).

Based on our experience with APIs and API documentation, we suggest that no API be exposed to the public if it doesn’t reach a minimum of 70% of Interface Completeness. More than that, we suggest 85% as indicating very good documentation, so it’s even better to use this value as a threshold. But this is only a suggestion; as everything in adaptive API governance, feel free to set the threshold value that works best for your context.

Suggestions to improve the Swagger file

The feature also displays improvement suggestions after it checks the Swagger file fields. To see them, click on SUGGESTIONS, below the percentage.

You can make modifications using the Swagger editor of Sensedia API Platform (see more information about it here).

After you make your changes and save your API as a new Revision, the completeness assessment is done again.

Usage example

We created an API with a description and base path, but we did not include any resource, which generated a low level of completeness:

Then, we included these two resources:
completeness ex2 resources

Using the Swagger editor of Sensedia API Platform, we included the types of return of each resource, error messages with the HTTP response codes for each resource and descriptions for some model properties. Our API is now ready to be exposed:

Fields checked

These are the fields that the feature checks to assess the level of completeness of an API’s documentation (note that there are different weights for each):

API	Resource/Operation	Model
Title Description Version Base path	Resource Operation summary Operation description Parameter name Parameter description Operation response code Operation response header name Operation response header description	Name Description Property name Property description

API

Resource/Operation

Model

Title
Description
Version
Base path

Resource
Operation summary
Operation description
Parameter name
Parameter description
Operation response code
Operation response header name
Operation response header description

Name
Description
Property name
Property description

How to use Interface Completeness with Workflows

The Workflows feature controls the stages of API development. On it, you can customize the requirements for an API to be promoted between the stages, which gives visibility and control of the development process of each API.

One of the requirements that can be set is a minimum percentage of Interface Completeness. In this case, if you define that only APIs with at least 85% of completeness must be in the "Production" stage and also include a requirement that only APIs in this stage can be deployed to a production environment, then you effectively establish that no APIs can be deployed to the public without satisfactory documentation!

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]