JoinDownload
This is drafted post. Please setdraft: falsein this .mdx file once ready to be published.

Most Popular API Specification

3 Min Read

Vyom Srivastava

API or Application Programming Interface, we have talked a lot about it in the previous posts. There are different types of API on the internet, some of them are public, some of them are private APIs and some of them are partner APIs. These APIs need to follow specific standards in order to become manageable as they’re written in different languages. This standard is known as API specifications.

API specifications are the standards that an API needs to follow so that it follows a specific structure and ability to diversify the system. It is a broad understanding of how an API works and how the API connects with the other third party APIs.

In API development, we see a variety of functions, modules, classes, etc calling each other and performing different sorts of functionalities. In API specification, we see how we implement these functions, how are they called and what they do. In addition to that, we see how they relate to each other.

There are different types of API specification on the internet. So, which one’s best for you? Let’s find out.

OpenAPI Specification (formerly Swagger)

It is a specification for REST API that defines a standard, language-agnostic interface which allows both humans and computers to understand and interact with the API with a minimum amount of implementation logic.

It can be used by API document generators which displays the API and generates the code snippets and other testing tools which use REST API.

This API specification is built using Semantic Versioning or semver and follows the semver specification in many places. Semantic Versioning is a versioning method which is used by software to release their updates. It works by structuring each version in three parts: MAJOR, MINOR, and PATCH. So it follows the structure like:

SOFTWARE_NAME MAJOR.MINOR.PATCH

OpenAPI Specification was formerly known as Swagger which was launched in 2010 and in 2015 SmartBear acquired the company and renamed it to OpenAPI Specification. Other founding members include Apigee, Capital One, Google, IMB, Intuit, Paypal and Microsoft.

RAML

RAML is like a YAML version for APIs. It uses YAML to describe the REST APIs and provides all the information which is required to practically describe the API. It is also able to describe the APIs which do not follow the constraints of REST APIs.

RAML promotes the use of code reusability, pattern sharing, and emergence of best practises. It was first proposed in 2013 and was authored by Uri Sarid, Emiliano Lesende, Santiago Vacas, and Damian Martinez.

RAML is also supported by organizations like MuleSoft, Angular, Intuit, Box, PayPal, Programmable Web etc.

Sample of RAML file:

#%RAML 0.8
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
traits:
- paged:
queryParameters:
pages:
description: The number of pages to return
type: number
- secured: !include http://raml-example.com/secured.yml
/songs:
is: [ paged, secured ]
get:
queryParameters:
genre:
description: filter the songs by genre
post:
/{songId}:
get:
responses:
200:
body:
application/json:
schema: |
{ "$schema": "http://json-schema.org/schema",
"type": "object",
"description": "A canonical song",
"properties": {
"title": { "type": "string" },
"artist": { "type": "string" }
},
"required": [ "title", "artist" ]
}
application/xml:
delete:
description: |
This method will *delete* an **individual song**

AsyncAPI Specification

It is an open-source initiative which improves the structure and semantics of Event Driven APIs or Asynchronous API. It is used to document and describe the message driven APIs in a low level readable format.

You can use AsyncAPI Specification for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, etc). It also defines a set of files required to describe such APIs. These files are used to create functions, documentation, integrations etc.

Sample of AsyncAPI Specification:

user/signedup:
subscribe:
$ref: "#/components/messages/userSignUp"

JSON Schema

This is one of the oldest API specifications and is split into two parts: Core and Validations. The JSON core schema defines the foundation of the JSON schema and JSON schema validation defines the keywords of JSON schema.

The meta-schemas are schemas against which other schemas can be validated.It is self-descriptive: the JSON Schema meta-schema validates itself. This specification is used for the validation of the JSON schema and also used for validation, extraction, documentation and interaction controller.

It is derived from XML schema but uses JSON for structuring and validation. Example:

{
"firstName": "John",
"lastName": "Smith",
"isAlive": true,
"age": 27,
"address": {
"streetAddress": "21 2nd Street",
"city": "New York",
"state": "NY",
"postalCode": "10021-3100"
},
"phoneNumbers": [
{
"type": "home",
"number": "212 555-1234"
},
{
"type": "office",
"number": "646 555-4567"
}
],
"children": [],
"spouse": null
}

API Blueprint Specification

It is a documentation oriented web API language which is used for the documentation of REST APIs. It is basically a set of rules and assumptions which is used to describe a web api with the help of Markdown.

It is built to encourage the collaboration between the project stakeholders, developers and customers for the maximum output at any step in the API development lifecycle.

Example:

# Blog Posts [/posts]
## Retrieve All Posts [GET]
+ Response 200 (application/json)
+ Attributes (array[Blog Post])
CONTENT
OpenAPI Specification (formerly Swagger)RAMLAsyncAPI SpecificationJSON SchemaAPI Blueprint Specification

Links

DownloadDocChange LogsCookiesTerms & ConditionsPrivacy PolicyContact Us

Apps & Integrations

HTTPGraphQLWebsocketSocketIO

Firecamp Newsletter