Common Mistakes Developers Make In Their API Blueprint Files

If you ever wanted to write a concise and human-friendly API description file, you must have come across API Blueprint. Using Markdown, the simple syntax of this high-level API description format makes it an easier choice for most of the developers out there. Rest assured that though simple, the format is no less powerful than the other popular ones out there like OpenAPI, RAML, etc. But while their files are mostly generated by tools or from code, API Blueprint, which is promoted as a “design-first” approach to APIs, is for the most part written by hand and is, therefore, more prone to human error.

In this blog, I will analyze each of the mistakes commonly observed in  API Blueprint files and highlight their frequency through failure stats collected on API Transformer over the past year (Aug 2017 — Aug 2018). You may find this blog similar to the ones I wrote previously on common mistakes found in OpenAPIand in RAML.

A shout-out to Kyle and Emmanuel from Apiary for taking out time to review my blog and providing valuable insights into the future of  API Blueprint.

Absence of Metadata

An  API Blueprint file uses Markdown which is a very commonly used documentation format. The Metadata section of an  API Blueprint file is an important part of it as it differentiates the file from any ordinary Markdown file. This section comprises of theFORMAT and an optionalHOST (if the service URL is known) as shown below:

Plenty of developers choose not to make this metadata part of their API description. While not explicitly deemed compulsory by the format owners in the specification, the FORMAT part of it is pretty much required. This is because with so many API description formats and various types of Markdown files out there, the absence of FORMAT makes it hard to recognize a file as an  API Blueprint  file. Approx. 24% of the total  API Blueprint failures on  API Transformer in the past year are attributed to this very issue. Fortunately, Apiary has been considering adding a version identifier to  API Blueprint in the future for the elimination of any such identification issues.

Incorrect Usage of Type System

Various components of an  API Blueprint file make use of a type system e.g. the payload (request/response) attributes, members of a named type, and the URI parameters.  API Blueprint  generally consists of two kinds of types:

1. Base types including primitive and structure types.
2. User-defined types called Named Types (or sometimes referred to simply as Data Structures)

MSON(Markdown Syntax for Object Notation) lets you define types in great detail in  API Blueprint. However, developers do not leverage the power of MSON as much as they should. Let’s have a look into this in more detail below.

Using Primitive and Structure types inaccurately

 API Blueprint makes available various base types that are listed here. 8% of the API Blueprint failures on API Transformer over the past year occurred because of small mistakes by developers like in trying to:

1. Use bool instead of boolean
2. Use numeric instead of number
3. Use list instead of array

Referenced Named types not defined in Data Structures section

Attributes and their members (or even those of  Named types) can reference other  Named types that are required to be defined under the Data Structures section. Several developers reference them without defining them first. Files with such cases constituted 15% of the total API Blueprint files that failed to convert on  API Transformer.

For example in the above case, it is required that the type used for the response attributes, OperationType, is defined under the Data Structures section as shown below. If not, you will see an error on the Apiary editor with a message like base type ‘OperationType’ is not defined in the document .

Confusing the syntax for specifying Attributes Type Definition

The  Attributes section  helps define a data structure using  MSON  for the payload, action and resource sections. The attributes can inherit from an existing data structure (say TypeName) and the syntax is generally:

However, a large number of developers sometimes use a syntax like the following:

This is invalid because in this case the base type is automatically assumed as object and the field+ (TypeName) is considered a member of this data structure with type TypeNameand a missing name (or “no identifier specified” as Apiary editor warns its users). 9% of the total failed  API Blueprint  conversions on  API Transformer were connected to this issue.

Rules Vary for URI Parameters Section

The  URI Parameters section  is unique because several rules that apply to this section do not apply to other sections that also make use of the type system. This is because while other sections use MSON, the type system used by this section predates MSON by a few years. The syntax does look similar but it is not equivalent. This can be confusing for most developers which apparently is the cause for the issues I am going to highlight below.  Apiary is working to eliminate all such inconsistencies in the future by introducing MSON to both the  URI Parameters  and  Headers  section. You can track the progress for it here.

URI parameter enum Type Section need explicit Members Type Separator

A lot of users tend to face issues related to enum values not getting loaded properly and this has to do with using the syntax for enum declaration incorrectly. 12% API Blueprint failures on API Transformer were found to be associated with this. Here is why:

Generally speaking, if you want to enlist the possible member values of an enumeration structure type (say value1 and value2)) you may list them in one line as:

Or maybe indent them nicely in a type section:

Or maybe add an explicit Members Type separator Members to indicate the section as containing Enum Structure members:

Although all are valid, the third representation is what is compulsory for the URI parameters section and you can confirm this syntax from their official specification documentation as well. So if you choose to not use this representation (and most developers don’t), the values will look in the  Apiary editor as:

With the correct representation, you will see the editor recognize the set of values correctly:

Open-Ended Type System

For the  URI parameters, it is a good practice to use only the primitive types and usage of complex types for  URI parameters is, therefore, seen very rarely. But developers feel the need to use different types based on their API design. And most of them do not define these types explicitly (like under the Data Structures section) which then creates trouble when using various tools.

The specification for  API Blueprint  poses no strictness as such for the type specification of these parameters because it simply says:

So if you choose to use any random type in this section (e.g. set, json, etc. ), the official editor won’t complain. However, this open-endedness, while suitable for documentation purposes, is not suited for tools like APIMatic that depend on these API description files for generation of client libraries and developer experience portals. This is because generation requires specific details of all types and any types other than the primitive ones cannot be comprehended by the tool unless explicitly defined. Hence, the largest portion of  API Blueprint failures on API Transformer (31%) pertained to this open-endedness.

Conclusion

 API Blueprint is a widely used format with a vast number of features and tooling available. MSON empowers it further through a type system that uses Markdown. In order to utilize MSON to its true potential, it is important to understand it fully. The learning curve for it is high and the specification feels a little overwhelming which is probably why most people tend to shy away from it. Perhaps providing more examples in the specification will help clear some of the ambiguities that developers face and allow for lesser mistakes.

Also since Apiary is working on improving API Blueprint in its future releases, we can expect lesser inconsistencies and, therefore, lesser issues in the description files. Meanwhile, you can head over to API Transformer to improve your existing API Blueprint file or to convert to other formats for free.