As with any industry, the web API space faces different approaches to standardization. Not least of which are the differences between how API providers choose to define their APIs in a machine readable way with API specifications and description languages.

API definitions have emerged as ways to annotate API functionalities, and there are still many out there catering to varying web service architectures. Working with varying languages like JSON, YAML, Markdown, RAML, or WADL, API definitions can be a powerful tool for things like generating interactive documentation or API testing.

While many experienced users understand the subtleties between terminologies in our realm, this does create somewhat of an entry barrier for those who aren’t long-term developers or veteran API evangelists. This is ever important when we discuss common ways Application Programming Interfaces are described.

Today, we’re going to describe some of the most widely used API definitions, seeing how each is used and where they fit into the API provider’s tool box. While we won’t cover every single definition ever created, our list will provide a solid introduction into varying API specification approaches, their chosen description languages, and their significance within the industry.

6 Common API Specification Types

We’ll first start by listing the most common specifications and description languages for web APIs.

OpenAPI Specification / Swagger

OpenAPI Specification: The OpenAPI Specification, formally known as Swagger, is a popular specification and framework implementation designed to be both human and machine readable. Because the OpenAPI Specification is simply the new name for the Swagger project and its various updates, this definition overlaps with Swagger.

Swagger: Swagger is an API framework specification based on JSON that is designed to be both machine and human readable. The Swagger specification is used to create a RESTful interface that maps resources and operations inherent to the API, allowing for ease of discoverability without the need to access source code or further documentation.

While the technical definition of Swagger would focus mostly on this framework, Swagger is also used to refer to the collection of resources which tie into it. The Swagger Editor, for instance, allows for the creation of a Swagger definition to tie into the Swagger Codegen tool to generate server implementations, which can then be explored via the Swagger UI exploration tool.

While versions 1.0 through 1.2 are still supported by many providers, most are moving towards 2.0 supporting JSON and YAML, which is known by its rebranded name of the OpenAPI Specification.

Swagger is language agnostic, with various developers extending this to language specification derivations and solutions supporting Scala, HTML5, Java, Actionscript 3, and others. This broad base is part of what drove the transition to the repositioning as “OpenAPI Specification”, as the solution is extremely extensible and open for mutation.

Swagger example from Apiary tutorials:

swagger: '2.0'
info:
  title: Polls Swagger
  description: Polls is a simple API allowing consumers to view polls and vote in them.
  version: "8234aab51481d37a30757d925b7f4221a659427e"
host: polls.apiblueprint.org
schemes:
  - https
paths:
  /questions:
    x-summary: Questions Collection
    x-description: ''
    get:
      summary: List all questions
      responses:
        200:
          description: 'List'
          examples:
            application/json:
              - question: "Favourite programming language?"
                published_at: "2015-08-05T08:40:51.620Z"
                choices:
                  - choice: "Swift"
                    votes: 2048
                  - choice: "Python"
                    votes: 1024
                  - choice: "Objective-C"
                    votes: 512
                  - choice: "Ruby"
                    votes: 256

RAML

RAML: RAML is a Modeling Language specifically designed to support both REST API documentation in addition to those who do not strictly adhere to REST standards, such as those that rely on SOAP or RPC architectures. This makes RAML very powerful, allowing developers to take advantage of extensively modified frameworks and other solutions not designed in the classical REST approach.

Make no mistake, however — RAML is still a REST-oriented approach to documentation.

RAML derives its form and function from YAML, a parsing data serialization format designed for human and machine readability, eschewing the all-but-ubiquitous JSON format. RAML is a top-down specification, documenting behavior of each element within the greater system from top to bottom.

Due to its design and philosophy, RAML can be used as much more than a simple documentation approach, and has indeed been used to great effect as a long-term API planning system. RAML can generate mock responses, trace function paths, and implement interactive API consoles natively, making it a great tool for both prototyping and live testing.

Example extracted from jukebox-api.raml from RAML 200 tutorial:

/songs:
  description: Collection of available songs in Jukebox
  get:
    description: Get a list of songs based on the song title.
    queryParameters:
      songTitle:
        description: "The title of the song to search (it is case insensitive and doesn't need to match the whole title)"
        required: true
        minLength: 3
        type: string
        example: "Get L"
    responses:
      200:
        body:
          application/json:
            example: |
              "songs": [
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440000",
                    "songTitle": "Get Lucky"
                  },
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440111",
                    "songTitle": "Loose yourself to dance"
                  },
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440222",
                    "songTitle": "Gio sorgio by Moroder"
                  }
                  ]
...

API Blueprint

API Blueprint: API Blueprint is a top-down specification, explaining the behavior of various sub-components and breaking apart the API itself as a method of documentation. API Blueprint utilizes Markdown, a well-known lightweight markup language amongst web developers and authors, in order to document APIs.

Unlike both RAML and Swagger, API Blueprint does not provide its own method to generate server code, and instead relies on third party integrations to do so. Additionally, API Blueprint utilizes C++ through Node.js and C# rather than utilizing Java and js as both RAML and Swagger do.

API Blueprint lacks several important features, such as advanced constructs and code level tooling, but is still a powerful implementation when used in the correct use case.

Example taken from the CloudApp API, described in API Blueprint:

FORMAT: 1A
HOST: https://api.cl.ly/

# CloudApp API


## Collection [/v3/collection]

### Fetch collection [GET]

+ Response 200 (application/json)

        {
            "data": [
                { "id": 1, links: [] },
                { "id": 2, links: [] }
            ],
        
            "links": {
                "next_page": {
                    "href": "/v3/collection?after=12345678",
                    "method: "GET"
                }
            }
        }
...

Mashery and I/O Docs

I/O Docs: I/O Docs, developed by Mashery, is an interactive documentation system for RESTful APIs. By defining APIs “at the resource, method, and parameter levels in a JSON schema,” I/O Docs generates JavaScript client interfaces dynamically, which can be used to execute calls.

I/O Docs was developed by TIBCO-owned Mashery, an API service and management firm whose focus extends beyond documentation, and into the creation and management of web services.

I/O Docs is a steadily evolving set of tools — after being purchased first by Intel and later by Tibco, I/O Docs and the entire Mashery ecosystem and service has grown exponentially. While there was initial complaints about lacking features, I/O Docs has evolved to support references, extensible authentication definitions, serialized JSON, and more.

Example from I/O Docs Definition from Mashery I/O Docs Configuration Guide:

{
 "name": "Example #1 API",
 "version": "1.0",
 "title": "The Key Only Auth API",
 "description": "The first example features API key based authentication only.",
 "protocol": "rest",
 "basePath": " https://api.example1.com/v1",
 "auth": {
 "key": {
 "param": "api_key",
 "location": "query"
 }
 },
 "resources": {
 "Product Methods": {
 "methods": {
 "Get Products": {
 "path": "/products.:format",
"httpMethod": "GET",
"description": "Get all products in our database",
"parameters": {
 ":format": {
 "type": "string",
"required": true,
"default": "json",
"description": "Output format as JSON or XML",
"enum": [
 "json",
 "xml"
 ],
"location": "pathReplace"
 }
 }
 }
 }
 }
 }
}

Google API Discovery Service

Google API Discovery Service: The Google API Discovery Service is Google’s method for creating machine readable metadata about Google APIs, and also acts as a system to build client libraries, plugins, and other content for Google APIs. The Discover API itself is based around JSON, and is designed to be machine-readable.

The Google Discovery document describes this sort of metadata. Example:

  "kind": "discovery#restDescription",
  "name": "urlshortener",
  "version": "v1",
  "title": "Lets you create, inspect, and manage goo.gl short URLs",
  "description": "Lets you create, inspect, and manage goo.gl short URLs",
  "protocol": "rest",
  "basePath": (Deprecated) "/urlshortener/v1/",
  "rootUrl": "https://www.googleapis.com/. Root URL under which all API services live",
  "servicePath": "/urlshortener/v1/. Base path for all REST requests",
…

WADL (W3C 2009)

WADL (W3C 2009): WADL, or Web Application Description Language, is a language that describes HTTP-based web applications in a machine readable format.

WADL was developed to supplant an area of documentation that’s often overlooked. While simple wiki or text documentation along with a schema document is adequate for human readers, this often needs to be converted or parsed into machine readable formats (or a new documentation generated into a machine readable format), which increases difficulty in understanding and leveraging.

WADL thus focuses on rendering the resources, relationships, methods, and formats behind the data in an API in a way that can be understood, explained, and leveraged by machines without a secondary translation layer.

The official documentation for WADL mentions several use cases that highlight why this is necessary. Processes such as Application Modelling and Visualization, Code Generation, and Configure of Clients and Servers typically do not have a direct human element working behind the scenes; accordingly, when human readable language is fed through, it must be translated to machine readable.

Other Honorable Mentions

APIMATIC Format

APIMATIC format is the default input format for APIMATIC. APIMATIC is an SDK platform management solution provider who boasts several key features as part of their literature.

First and foremost, they promote the generation of customized SDKs over a cloud-based methodology. They further promise scalability and integration within a variety of programming stacks. These features and more are used as a set of tools to generate what APIMATIC calls “simple SDKs that your development teams will love.”

HAR 1.2

HAR 1.2: HAR 1.2 Spec, otherwise known as the HTTP Archive Spec, is a format used by HTTP monitoring and alaytics tools to export data. HAR was designed to be flexible for malleability between projects and for compatibility across various tools, allowing for more effective processing and analysis.

The format is formally based on JSON. HAR utilizes UTF–8 encoding, and represents data in a variety of object types like “pages”, “content”, and “timings”.

Interesting, HAR has the benefit of being developed and implemented by the World Wide Web Consortium, also known as the W3C. W3C is the main standards body for the world wide web, and thus HAR is generally considered to be, once completed, a universal system for data formatting of this type.

It is worth mentioning, however, that unlike other entries in this list (such as OpenAPI Specification, which is a rebranding of a former system, Swagger), HAR 1.2 is still in the draft phase.

Rapid-ML

Rapid-ML: RAPID-ML is an approach to API design which focuses heavily on data modeling. It describes data types using a “technology-independent” language, and is often marketed as a way to “integrate faster” and “free […] client developers from API mismatch”.

Rapid-ML handles this using JSON and XML schema generators that tie into shared data models from local machines or http repositories, and use bound resources and parameters in the API to validate and generate code.

One of the big selling points for Rapid-ML is the idea of displaying, using, and understanding referenced data structures as a hyperlink, embedded structure, or both. By doing this, in theory, round trips are optimized and data bandwidth reduced (though whether this actually happens in practice is determined by many more variables than just Rapid-ML.

Conclusion

Keep in mind that this is not a complete resource — there has certainly been other attempts to construct machine readable API specifications and metadata for standardizing how we define APIs. That being said, this represents the bulk of the most common API specification types that you will currently find throughout the modern API landscape. Now in terms of which to use, we’ll explore some in more detail to come. Of course, with such great momentum put into the Open API project and surrounding tooling community, it’s quite possible this list could be dramatically shortened soon.