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 request 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 de deployed in a production environment if their documentation is ok.

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

There’s no specific page for Interface Completeness; it shows on the upper right corner of an API’s Overview screen:

completeness

The feature analyses the API’s Swagger and compares que 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 exhibit APIs on the Developer’s Portal on the API’s Overview screen).

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 itens 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 if the description is well suited to what the API does or 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 to 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 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 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 (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.

Example of use

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

completeness ex1

Then, we included these two resources:
completeness ex2 resources

Using the Manager’s Swagger editor, 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:

completeness ex2

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

How to use Interface Completeness with Workflows

The Workflows feature controls the stages of API development. On it, you can customise 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!

You can read more about Workflows here.

Thanks for your feedback!
EDIT

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