Documenting a REST API is important for its successful adoption. APIs expose data and services that consumers want to use. An API should be designed with an interface that the consumer can understand. API documentation is key to the app developers comprehending the API. The documentation should help the developer to learn about the API functionality and enable them to start using it easily. This chapter looks at the aspects of documenting an API and some of the tools and technologies available for API documentation , including RAML, Swagger, API Blueprint, and others.
The Importance of API Documentation
As an API provider or developer, you may master your API. You have inside knowledge about its functionality, what it is supposed to do, how it is to be used, its security, limitations, error scenarios, and so forth. As an API provider, you have gradually learned everything about the API through various discussions, documentation, and references. However, this is not the case for the consumers of your API. The app developer community or API consumers look at the API’s interface and wonder what the API does, how it should be used, what to expect when an error occurs, what security credentials to use, how and where to get the security credentials to use the API, and so forth. Hence, what is easy and simple to the API developer may not be intuitive to the API consumer. Good API documentation can help bridge the gap and make the API successful. API documentation communicates a vast amount of information about the API.
As enterprises move along in the digital transformation journey, there has been exponential growth in public and private APIs . In this competitive world, it is very likely that the data and services exposed by your API may also be exposed by another API provider. If the API is being monetized, it becomes more important to make it successful for your business. Good user-friendly API documentation is a key to its successful adoption. An API document is like an entrance into your API and provides a warm welcome to the API’s consumers.
The API documentation should
Get users started quickly
Include useful and relevant information
Provide sample code
Document a list of REST endpoints
Document the message payload
Provide Response status code and error messages
Audience for API Documentation
API documentation is used by various groups of people for various reasons. It is like a user manual for a product. Like a user manual, API documentation should have a quick-start guide, which quickly makes the first API call and lets consumers have a feel of it. At the next level, it should document the API’s features, the resources and the APIs to access them, and finally, the error conditions for troubleshooting. Hence, the API documentation can be used primarily by the following types of audiences.
CTO: Evaluates similar and competing APIs from a business, technology, and monetization perspective.
App or integration architect: Explores the API to match the requirements for building an app or an integration solution.
App developer: Wants to get started using the API with a quick-start guide and a detailed tutorial. Sample SDKs and API calls in the API documentation is of immense use to an app developer.
IT support specialist: Supports the app and is interested in the error and troubleshooting information for debugging any issues with the app.
Model for API Documentation
A good API document communicates all information about the usage of the API— for both humans and machines. The API document should provide all necessary information to app developers or API consumers in a human-readable format. The documentation should help them assess its suitability for use in their client app. It should provide information about its licensing policy and usage requirements-input and output parameters, message format, error messages, and more. Similarly, the API interface should be documented such that its interface can be parsed by a machine to generate client stubs and server-side skeleton code that can be further developed. To make API documentation effective, it should include the following aspects about the API:
Title
Endpoint
Method
URL parameters
Message payload
Header parameters
Response code
Error code
A sample request and response
Tutorials and walkthrough
Service-level agreement
Figure 4-1 shows an example of API documentation using Swagger.
Figure 4-1. API documentation using Swagger
Title
The titleshould provide the name of the API, which can be used for its identification.
Endpoint
The endpointis the entry point for the API. It defines the URL that clients need to use to invoke the API.
Method
The methoddefines the HTTP verbs used to access the API. GET, POST, PUT, and DELETE are the most common HTTP verbs used in a REST API. The client should specify the methods along with the URI to access the API. If an API supports multiple methods to be used for an URI, it should be specified in the API document as separate entities, as shown in Figure 4-1.
URL Parameters
The URL parameters define the parameter names and their format , which are used in the API call as a query string. The documentation should clearly state the purpose of each parameter, as well as which parameters are mandatory and which are optional. Any requirements for URL encode should be documented.
Message Payload
The message payload should specify the structure and format of the request and response message. JSON and XML are the most common formats used for a REST API. Other formats can be used as well. The message structure should specify the schema of the message payload . Any data constraints in the request payload should be documented. It is a good practice to include a table that provides the name, data type, description, and remarks, if any. Figure 4-2 shows a snippet of a Swagger format specification of an API, with the message format for a request and response payload.
Figure 4-2. A snippet of a Swagger format specification with the message format for a request and response payload
Header Parameters
The header parametersshould specify the standard and custom HTTP headers included in the request and response headers. At a minimum, all mandatory headers should be specified here. Any specific format for the header values must be included.
Figure 4-3 shows a snippet of an API documentation in Swagger format with the header parameters defined.
Figure 4-3. A snippet of a Swagger format specification with the header parameters defined
Response Code
The HTTP response codes that the client can expect from the API under various conditions should be included in documentation. It is important to document which response codes are considered successful and which are considered errors. All possible response codes, what each of them means, and their root causes should be specified. This helps the API consumer more easily troubleshoot issues.
Error Codes and Responses
Normally 4xx and 5xx HTTP response status codes are considered errors . HTTP specifications define the purpose of these status codes. Not all HTTP response status codes may have been implemented for an API. The API documentation should include the HTTP response status codes that the API consumer can expect in different error scenarios. Along with the HTTP response status code, the sample error response payload should also be specified. This helps the consumer application parse error messages. The error response payload may include specific business error codes and descriptive error messages that offer information about the exact cause of the error. All error codes and error messages should be defined in the API documentation.
Figure 4-4 shows a snippet of a Swagger format specification in an API document, with the response code and error codes defined.
Figure 4-4. A snippet of a Swagger format specification with the response code and error codes defined
Sample Calls
As part of the documentation , include sample HTTP calls with all parameters and expected sample responses. This gives the developer a visual sense of what the message structure should look like. Include samples for all the various message formats supported, such as XML, JSON. Sample calls can be included in a wiki format or as interactive smart docs. Figure 4-5 is an example of a sample GET call for an API.
Figure 4-5. A sample GET call
Tutorials and Walk-throughs
An example is always better than tons of documentation. Hence, a tutorial with example code on how the API can be called from an app is always very helpful to the developer community. Sample SDKs for making API calls in some of the most popular languages—such as Java, Node.js, C#, PHP, Ruby, and Python—helps developers quickly adopt the API. Including SDKs for different digital platforms—such as Android, iOS, and Windows—is highly recommended. Including code for all languages and platforms may not be always feasible; hence, you should evaluate the most popular languages and focus on including tutorials and sample code for them.
Service-Level Agreements
A service-level agreement (SLA) defines the API’s non-functional requirements.This can include the expected throughput, response time, rate limits for various tiers (if applicable), maintenance or downtime information, and so forth.
API Documentation Standards: Swagger, RAML, and API Blueprint
The daunting task of API documentation is keeping the documentation in sync with the actual implementation. If you take a bottom-up approach and create the API documentation manually after the implementation, you risk the documentation falling out of sync if there are enhancements to the API interface in the next version, especially if the process does not enforce regeneration or validation of the API document. Similarly, with a top-down approach, you may start with the API documentation and manually create the skeleton of the API interface according to the defined interface. But later, you still run the risk of the API documentation getting out of sync with the actual implementation when enhancements are required. Hence, defining the API Interface and keeping the documentation in sync is a big challenge. This challenge can only be addressed if there are tools that autogenerate API documentation from the API Interface in a bottom-up approach, or tools that generate the API skeleton and client code from the API interface document in a top-down approach. Standards and tools based on these approaches are definitely needed to aid in API documentation.
There are many competing tools for API documentation. Some of them are in a fairly matured state, while others are still evolving. The next few sections look at the Swagger, RAML, and API Blueprint frameworks so that you can see how they are used to document an API interface. The tools that they provide are also discussed.
Swagger
Swagger is one of the most popular API documentation frameworks. It provides a standard, language-agnostic way of defining a REST API interface. This approach allows the client to understand the capabilities of the REST service without any prior access to the service implementation code or network inspection. The goal of Swagger is to keep the client, API documentation, and API server implementation in sync. The Swagger framework comes with the following:
OpenAPI Specifications for documenting RESTful APIs
Swagger UI to graphically display the API interface
Tools like Swagger Codegen to generate clients for different languages
On January 1, 2016, the Swagger specification was renamed the OpenAPI Specification when it was donated to the Open API Initiative.
The Swagger specification defines the format to describe the REST API. The Swagger specification describes the following information about the REST API.
URL endpoint
HTTP verbs supported for the URI
Description
Query parameters to be passed in the URL
Header parameters in the input request message
Payload format and data type for the request and response messages
HTTP response status codes
Security requirements
Vendor extensions
An API’s Swagger specifications are documented in JSON or YAML format. Swagger-enabled APIs expose JSON files that adhere to the specifications. The API specification can be a manually generated static file or automatically generated from the application. The API specification needs to be documented in a certain way as per the structure defined by the Swagger specifications. We look at the high-level structure of a Swagger definition file for an API later in this chapter.
The Swagger UI provides a framework to dynamically generate beautiful interactive documentation from a Swagger-compliant API. It is an independent collection of HTML, CSS, and JavaScript that can be hosted on any server. It can be used by consumers to explore and interact with the API and understand its behavior. API users can use the Swagger-UI to test the API and learn about how the API responds to various parameters and options. The Swagger-UI can be used as-is or customized to meet an organization’s needs. The Swagger-UI provides support for HTTP verbs, such as GET, POST, PUT, DELETE, PATCH, and OPTIONS for API invocation. Authorization and custom HTTP headers can be added to the Swagger-UI. It also provides support for localization and translation.
Swagger Codegenprovides tools for generating code for the client and server from the Swagger-defined API spec. It is a command-line tool that can generate code for different languages and frameworks. Some of the frameworks that are supported for server stub generation are Node.js, PHP Silex, Python Flask, Scala Scalatra, Java JAX-RS, and Java Spring MVC. Client-side stubs can be generated for languages such as Scala, Java, JavaScript, Ruby, and PHP—to name a few. Refer to the documentation at https://github.com/swagger-api/swagger-codegen for more information on this tool .
The Swagger Editorcan be used to edit the Swagger API specification in YAML format. The editor is opened in a web browser to edit the specification and preview the API documentation in real time.
Generating Swagger Specifications
Both top-down and bottom-up API development processes can be adopted to create a Swagger-enabled API.
Top-down approach: Creates a Swagger definition using Swagger Editor and uses integrated Swagger Codegen tools to generate server implementation.
Bottom-up approach: Uses Swagger Editor to manually generate Swagger definitions, or autogenerates Swagger definitions created using Swagger supported tools, such as JAX-RS or Node.js.
The Swagger File Structure
The Swagger-based API specification is documented in JSON or YAML format. The Swagger specifications include the following in the API interface.
swagger: Describes Swagger specification version
info: Shows the API’s metadata
host: The hostname or IP serving the API
basePath: The base path on which the API is served relative to the host
schemes: The protocol that the API uses
consumes: The MIME type for the API’s input data type
produces: The MIME type for the API’s output data type
paths: The API’s available paths and operation
definitions: Holds the data types produced and consumed by the operation
parameters: Describes a single operation parameter
responses: Describes the schema of a single response of an API operation
securityDefinitions: Describes the security mechanisms without enforcing them on the operation
securitySchemes: Specifies the security definitions that are enforced for the API’s operation
tags: Specifies any additional information on the API
externalDocs: Specifies links to any additional external documentations related to the API
For more information on each of these Swagger objects, please refer to the Swagger specification at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md .
Table 4-1 lists the various major Swagger tools available at the time of this writing. OpenAPI community is constantly generating new tools to expand the reach of Swagger for different platforms in API development.
Table 4-1. Swagger Tools
Tools | Description |
|---|---|
Major Tools | |
Swagger Core | A set of Java libraries for generating and consuming Swagger definitions built around JAX-RS. |
Swagger Codegen | Tools that generate client libraries and server stubs based on the Swagger definition. |
Swagger UI | A browser-based UI for exploring Swagger-defined APIs. |
Swagger Editor | A browser-based editor for authoring Swagger definitions in YAML or JSON format. |
Other Tools | |
Swagger JS | A JavaScript client for use with Swagger-enabled APIs. |
Swagger Node | Tools for designing and developing Swagger-compliant APIs entirely in Node.js. |
Swagger Socket | This protocol allows any existing REST resources to be executed on top of the WebSocket protocol. |
Swagger Parser | A standalone library for parsing Swagger definitions from Java . |
RAML
RAML stands for RESTful API Markup Language. It is a Markdown-based language for modeling APIs. It makes it easy to manage the entire lifecycle of an API: design, build, test, document, and share. RAML is both machine-readable and human friendly. RAML is designed to support an API-First top-down development approach. It provides the format for the contract between the API provider and the API consumer.
Why RAML?
RAML designs API interfaces that are developer- and user-friendly. Using RAML, API interfaces can be designed, tested, and shared with users to get feedback without writing a single line of code. APIs can be described in a human-readable text format. Tools like API Workbench and API Designer provide visual design. The RAML construct lets you reuse libraries, code, and design patterns in the API design, which saves lot of work.
RAML code generation tools create server-side code from the spec for different languages, such as Node.js, Java, JAX-RS, .NET, Python, Mule, IoT, and others. A RAML specification can also generate test cases for the API using many of the open source and commercially available API testing tools. This takes advantage of the test- driven development approach and generates test cases than can be integrated with the continuous improvement process.
API documentation can be easily generated dynamically on the fly from RAML with tools such as API Console, RAML2HTML, API Notebook, and others. This keeps the API documentation in sync with the implementation. API definitions in RAML can integrate with other systems. Many open source and commercial tools available today can generate SDKs for different languages from RAML definitions.
Professional services such as APIMatic.io and REST United offer to generate up to two SDKs at no cost. Oracle and MuleSoft provide built-in functionality in their API management products to import the RAML definition, which automatically pulls in the API resources, methods, and other properties, thus avoiding any manual setup of API calls in these tools. With API Notebook, developers can use RAML definitions to create interactive API walk-throughs and sample use cases using simple JavaScript.
More information on API Notebook is at https://api-notebook.anypoint.mulesoft.com .
RAML Structure
This section looks at the high-level structure of a RAML-based API specification document. The detailed schema and syntax can be found in the RAML specifications document at https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md .
A RAML API specification can be structured and organized into the following sections.
Security scheme information: Describes the basic information about the API , such as title to identify the API, its version, the baseURI to specify its network location for invocation, supported protocols, and default media type and security requirements. Any user documentation that can serve as user guide or reference documentation can also be optionally included in this section.
Data type: The data type is used to describe any data that is passed as a parameter for the API. A parameter can be in the URI as query parameters, in the header as header parameters, or in the request/response body. The data can be described using built-in types or by a new custom type definition created using a combination of the built-in data types. The data types can be defined using XML or JSON schemas, or RAML types. These can coexist as well. For more information on the data types definitions allowed in the RAML spec, please refer to https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#raml-data-types .
Resources: Specifies how to access the API’s resources and subresources using URIs relative to the baseURI. The resources definition should start with a slash (/). A resource defined at the root level is called the parent resource. Each parent-level resource is identified using its own URI relative to the baseURI. Each parent resource may optionally have one or more child resources defined under it. This approach builds and defines a nested hierarchy of resources. The relative URI of a resource may consist of multiple URI path fragments separated by slashes; for example, /cart/items. This approach can be used only if an individual path item is not a resource. If the path items are themselves separate resources, then they should be defined as nested subresources. These is no limit to the level of resource nesting that is allowed. Template URIs containing URI parameters can be used when the resource identifier is a variable; for example, /products/{productId}. For more information on defining resources and nested resources using RAML, refer to https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#resources-and-nested-resources .
Method: Describes the allowed HTTP verbs and the request parameters that can be used to manipulate a resource. The HTTP verbs that can be specified are GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. Each method can have an optional friendly name and description to describe its functionality. Any optional or mandatory HTTP headers required for a method should be specified under this section. The structure and any constraints or patterns of the header parameters that the API consumer should be aware of needs to be specified here. Similarly, any optional and mandatory query parameters to be passed as query string should also be specified. The request body for POST and PUT methods can be optionally described in this section. For more information on using method in a RAML definition, please refer to https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#methods .
Response: Contains the schema and description of the response object received from the service for a method invocation. The response has two main sections: header and body. The header describes the possible HTTP status codes expected in the response header under various conditions. The body is optional and describes the media type and the structure of the message payload included in the response body. The structure can be defined using types defined in the data type section. For more information on the response definition, refer to https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#responses .
Resource types and traits: Resource types and traits define reusage patterns and resources across the RAML definition. You may want to define the pattern for a HTTP header, or a query parameter, or a message payload, and then reuse it at different places within the RAML definition. A resource type is a partial definition of a resource that can specify security schemes, methods, and other properties. A resource that uses a resource type inherits its properties. A resource type can use another resource type. Traits are similar to resource types. The difference is that a trait is a partial method definition. It can be used to define method parameters, such as headers, query strings, and responses. Resources and resource types can also use and inherit from one or more traits. For more information on resource types and traits, refer to https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#resource-types-and-traits .
Security: The API security scheme definition is specified in this section of the RAML definition. This section defines the OAuth, Basic Authentication, or Digest Authentication mechanism for API security. Any other forms of authentication can also be specified using x-<other> headers. Any headers or query parameters that pass through can also be specified in this section under the ‘passthrough’ attribute. If any API method requires a special security mechanism, it can be specified by the ‘securedBy’ attribute for that method. This overrides whichever security scheme has been applied to the API as a whole. If a method does not require any security scheme, it can be specified by the ‘securedBy’ attribute for that method with a null value. Multiple security schemes for a method can also be specified using the securedBy element with an array list of security schemes .
RAML Tools and Projects
RAML is supported by the developer community with a long list of tools and projects that address different API needs. These tools address different aspects of the API development lifecycle—from designing the API spec to sharing it with the broader community. New tools are also evolving to address newer requirements and languages. Some of the languages supported at the time of this writing are Java, JavaScript, .NET, Ruby, Node.js, Python, Go, and Haskell. This section briefly previews the most commonly used RAML tools.
API Workbench is a tool by MuleSoft that provides a full-featured integrated development environment (IDE) that design, build, test, document, and share RESTful APIs. Using API Workbench, you can create RESTful APIs using a simple design-first approach based on RAML specifications. It supports both RAML 0.8 and RAML 1.0 versions of the specifications. This tool is based on Atom code editor developed by GitHub. The following are some of the main features of API Workbench.
An IDE that supports autocomplete, advanced search, live debugging, and symbol based navigation
Dynamic generation of API Mocking Service and API Console
Wizard-driven creation of API definitions based on RAML specifications
Automatic validation of RAML-based API definitions
Built-in support for integration with Git for source control and versioning
An integrated scripting engine and tooling for API testing and documentation
API Designer is a tool from MuleSoft that allows a user to see real-time post-processing of their API definition. It provides three panels with areas to organize RAML files and folders, displays the contents of the document, and offers an interactive text editor. The text editor provides features such as autocomplete, export, and contextual tag lists. It also saves the API definition. For more information, please refer to https://github.com/mulesoft/api-designer .
Restlet Studio provides a lightweight integrated development environment that can help accelerate API design. Built using Angular.js, it provides a web-based UI for API design. The following are some of the main features for Restlet Studio:
Visual web-based editor to define and edit API definitions for endpoint, resources, methods, and so forth.
The ability to group resources and representations into sections with scrollable a navigation panel helps extend support for even the most complex API definition
A built-in language translator switches between Swagger and RAML definitions
Generates server skeleton code using a built-in code generator service based on APISpark and Swagger
Generates client SDKs using a built-in code generator service based on APISpark and Swagger.
For more information on Restlet Studio, please refer to http://restlet.com/products/restlet-studio/#.
API Notebook is another RAML tool by MuleSoft. It helps with live testing and exploring APIs . An API RAML definition can be imported into Notebook to create a client for the API, send requests, and view responses. Notebook’s autocomplete feature explores the API. Once a RAML definition for the API has been imported, the method definitions will appear in the tool-tip hints. The path segments of the API resource, separated by slashes (/), become nested JavaScript objects; for example, /my/myresource becomes {clientName}.my.myresource.
RAML for JAX-RS provides a set of tools that generate a Java + JAX-RS-based application from a RAML API definition. It also provides roundtrip support by doing the reverse to generate a RAML API definition from an existing Java + JAX-RS definition.
Abao provides a REST API testing tool for APIs defined using RAML. It tests the RAML definition for the API against the back-end implementation. This tool can be integrated with continuous integration (CI) tools such as Jenkins to test API documentation and keep it up-to-date. It uses the Mocha framework to test the validity of the API response. The following are some of its features:
Validates the API endpoint definition
Validates that each URL parameter defined in the RAML API spec is supported in the back-end service
Validates that each HTTP request and response header parameter defined in the RAML API spec is supported in the back-end service
Validates that the JSON schema for the request and response payload meets RAML specifications
RAML Tools for .NET provides a Visual Studio extension for RAML-based APIs. It allows you to easily integrate and consume APIs defined using RAML and to create a new ASP .NET REST API implementation from a RAML definition using a design-first approach.
There are many other tools available as RAML projects that address the various needs of the developer community building and consuming REST APIs from a RAML definition. Based on the functionality, these tools can be primarily categorized by design, prototype, build, frameworks, test, document, share, parser, and converters. Most of the design tools provide a visual interface or plugins that can be used with other visual editors to design the RAML definition for the API. The prototype tools can be used to mockup response for APIs defined using RAML. They can test the API interface and create stubs as a replacement for the actual implementation for testing purposes. The build tools and frameworks generate the client SDK and server skeletons based on the RAML definition of various languages. This promotes the design-first approach for API development.
These tools test API documentation and implementation. They can generate test cases for APIs based on the RAML definition for the API. They validate the RAML definition against the actual implementation and thus keep the two in sync. The documentation tools create API documents in various formats; graphical API consoles, HTML, wikis, PDFs, and other formats can be shared with API consumers. The parser tools are libraries for different languages, which parse the RAML definition of the API. The converters convert the RAML to other API specification formats, such as Swagger.
Differences in RAML Specification Versions
At the time of writing , RAML has two versions: RAML 0.8 and RAML 1.0, which is in a release candidate (RC) state. RAML 1.0 provides more extensibility, code reuse, and flexibility features than the previous version. It introduces new features, such as libraries, overlays, improved security schemas, data typing, annotations, and enhanced examples.
Libraries let you to include predefined sets of data types, resource types, security schemas, traits, and reusable assets.
Overlays give the flexibility to include new information, such as descriptions, examples and annotations, which are defined in a different RAML file; for example:
#%RAML 1.0types: !include myTypes.ramlSecurity schemas have been enhanced to provide better support for OAuth 1 and 2, a new API key, and new custom security schemes.
Data typescan be used in place of schemas and examples. The data type definition can be converted to XML or JSON format on the fly using some of the RAML tools. API designers can thus define only the data type for their input and output parameters and RAML takes care of the REST.
API Blueprint
API Blueprint is a document-oriented language for describing REST API using Markdown syntax. This specification, brought in by Apiary.io, uses Markdown syntax to describe the complete specification of an API or its parts.
API Blueprint Document Structure
An API Blueprint document is structured into logical sections. For example, headers, URL parameters, and request/response can each be described in logically grouped sections. Each section is defined by predefined keywords. Depending on the section, the keyword is written either as a Markdown header entity or a list item entity. The following are the reserved keywords for defining the header and list entities in an API Blueprint document:
Header keywords
Group
Data structure
HTTP methods
URI templates
Combination of HTTP methods and URI templates
List keywords
Request
Response
Body
Schema
Model
Header and headers
Parameter and parameters
Values
Attribute and attributes
Relation
At a high level, the API Blueprint description for a REST API is organized in the following structure:
Metadatadescribes the version of the API Blueprint specification used for documenting the API interface. It also contains the API name and a brief description.
Resource and resource group describe the resources and the group of related resources used by the API. For example, in an online shopping experience, a customer may have one or more orders. So orders is defined as a resource group; within this group there can be a resource that returns a collection of orders.
Actions describe the operations that can be performed on a resource. It is specified using one of the HTTP verbs within square brackets.
URI templates specify the variable parameters in the URI; for example, an order may be identified using an order ID. So to get the details of a specific order, you specify it using /orders/{order_id}.
URI parameters describe the variables being passed in a request URI or as a query parameter; for example, /path/to/resources/{varone}?path=test{&vartwo,varthree}.
For more information on each of these keywords, please refer to the API Blueprint Specification document in GitHub at https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-api-blueprint-language .
API Blueprint Tools
The API Blueprint spec is supported by a good number of tools. This section discusses some of the most commonly used API Blueprint tools.
Apiary.ioprovides a comprehensive tool that supports collaborative design, creation of API mockups, automated testing, autogeneration of interactive API documentations, API traffic inspection, and more.
Dreddis an HTTP API testing tool. It is a command-line tool that can be used to test the API documentation written in API Blueprint against the back-end implementation. This tool can be integrated with CI tools to ensure that API documentations are always up-to-date.
Drakovprovides a Node.js implementation of a mock server for APIs written using API Blueprint.
There are many other open source tools that support the API Blueprint format for SDK generations. They have various language formats, testing API interfaces, and plugins for API test clients; they can also convert API definitions from other formats to API Blueprint and vice versa. Since API Blueprint and its tools are open source, they can be freely integrated with all kinds of products to extend support for API Blueprint.
Comparing Swagger, RAML, and API Blueprint
Tables 4-2, 4-3, and 4-4 compare Swagger, RAML, and API Blueprint .
Table 4-2. Overview Comparison
Criteria | Swagger 2.0 | RAML | API Blueprint |
|---|---|---|---|
Format | JSON, YAML | YAML | Markdown |
Availability on Web | GitHub | GitHub | GitHub |
Primary sponsor | Reverb | MuleSoft | Apiary |
Is there a workgroup? | Yes | Yes | No |
When was it first committed? | July 2013 | September 2013 | April 2013 |
Design approach | Top-down and bottom-up | Top-down | Top-down |
Current version | 2.0 | 1.0 | A4 |
Table 4-3. Tool Support
Criteria | Swagger 2.0 | RAML | API Blueprint |
|---|---|---|---|
Authoring tool | Swagger.io | API Designer | Apiary.io |
Ad-hoc testing | Swagger UI | API Console | Apiary.io |
Documentation | Supported | Supported | Supported |
Mocking | Extended support provided by third party | Extended support provided by third party | Extended support provided third party |
Server code | Supported by third party | Supported by third party | Supported by third party |
Client code | Supports multiple languages | Supports multiple languages | Supports a few languages |
Generate from code | Supported by Java (third party) | Supported by third party | Supported by third party |
Validation | Supported | Supported | Supported |
Parsing | Java.js | Java.js | C++(Node.js, C#) |
Table 4-4. REST Modeling Capabilities
Criteria | Swagger 2.0 | RAML | API Blueprint |
|---|---|---|---|
Resources | Supports resource definition | Supports resource definition | Supports resource definition |
Nested resources | Supports nested resource definition | Supports nested resource definition | Supports nested resource definition |
Representation metadata | Supports the JSON schema | Supports inline and external definitions in any format | Supports only inline definitions in any format |
Composition/ inheritance | Inheritance supported by sub types | Supports inheritance of traits and resource types | Supports resource model inheritance |
API version metadata | Supported via apiVersion tag | Supported via version tag | No explicit tag to specify the API version |
Authentication | Has tags defined to support Basic, API Key, and OAuth2 | Supports Basic, Digest, and OAuth2 | Supported via custom header definitions |
Methods/action | Supported | Supported | Supported |
Query parameters | Supported | Supported | Supported |
Path/URL parameters | Supported | Supported | Supported |
Header parameters | Supported | Supported | Supported |
Documentation | Supported | Supported | Supported |
Other API Documentation Frameworks
Swagger, RAML , and API Blueprint are the most popular API documentation standards. Most API management vendors include support (in various forms) in their tools for one or more of these languages. However, these specs are still evolving. In parallel, there have been efforts from various corners to create specs that address competitors’ shortcomings. As a result, many competing specs are available today from various vendors. These are in various levels of maturity. The following is a list of some of the other API standards used for modeling and documenting APIs:
WADL
ioDocs from Mashery
Doxygen
ASP.NET API Explorer
Apigee Console To-Go
Enunciate
MireDot
Dexy
Docco
TurnAPI