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:
-
Base types including primitive and structure types.
- 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:
- Use
bool
instead of boolean
- Use
numeric
instead of number
- 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.