Top Specification Formats for REST APIs | Nordic APIs | (2023)

Kristopher Sandoval

Top Specification Formats for REST APIs | Nordic APIs | (2)Documentation will set you free. Whether your API is for internal, private use, or for extensive public interaction, proper documentation can make or break an API. It’s not just a tool for developers, either — proper API documentation can drive API adoption more than any other tool within the API provider’s grasp.

In this piece, we’re going to discuss three of the most popular API documentation and specification formats — OpenAPI Specification (Swagger), RAML, and API Blueprint — and address how properly utilizing them can lead to intense and continuous growth. We’ll briefly discuss some alternatives — WADL and Slate — and how they fit into the API documentation space. We’ll touch on the strengths and weaknesses of each format, as well as some general caveats to be aware of when adopting a new documentation method. Finally, we’ll provide some real-use applications of these specifications in code form.

Also read: How to Spark Good API Documentation Practices

OpenAPI Specification

Top Specification Formats for REST APIs | Nordic APIs | (3)Of the many API documentation and specification formats, OpenAPI Specification (previously Swagger)is certainly one of the most popular. To call Swagger a “documentation” or “specification” format, however, is somewhat misleading. Developed by Reverb Technologies to be a specification and complete framework implementation, Swagger is used both to generate API server code, client code, and the documentation for those services.

Swagger’s entire focus is on streamlining and synchronizing the update workflow. Because the server and client code is generated and documented at the same time, they can be updated simultaneously. The server code is closely integrated with the documentation methodology, allowing for clean, usable, and understandable documentation.

One of the few caveats of Swagger is the fact that it’s language-agnostic. On the surface, this seems like a good thing — after all, having a broad base of functionality and usefulness is generally positive.

(Video) OpenAPI 3.0: How to Design and Document APIs with the Latest OpenAPI Specification 3.0

Unfortunately, being language-agnostic limits its value as a broad-base documentation framework when compared with more language-specific or language-supporting frameworks, and can make the process of identifying compatible third party APIs or server-based extensions and solutions that much harder.

Accordingly, a few developers have implemented language specific derivations of the Swagger documentation framework, supporting Scala, HTML5, Java, Actionscript 3, and others.

Using Swagger

Swagger documentation is relatively straightforward — once the endpoint is set, operation documentation is strictly a matter of utilizing the @ApiOperation and @ApiParam annotations to define functionality and the parameters required to carry out specific operations. First, set the endpoint:

/** * REST endpoint */@Api(value = "users", description = "Endpoint for user management")@Path("/users")public class UsersEndpoint {...}

And then begin tagging the code with the variable annotations provided:

@GET@Path("/{userName}")@Produces(MediaType.APPLICATION_JSON)@ApiOperation(value = "Returns user details", notes = "Returns a complete list of users details with date of last modification.", response = User.class)@ApiResponses(value = {@ApiResponse(code = 200, message = "Successful retrieval of user detail", response = User.class),@ApiResponse(code = 404, message = "User does not exist"),@ApiResponse(code = 500, message = "Internal server error")})public Response getUser(@ApiParam(name = "userName", value = "Alphanumeric login to the application", required = true) @PathParam("userName") String userName) {...}

Additional alternative functionality is represented in Swagger quite easily. In the above example, multiple @ApiResponse annotations were nested under the @ApiResponses annotation, allowing documentation to cover a wide variety of possible responses and functionality within the API code. This allows for extended testing of possible responses, as well as laying out a sort of “roadmap” for possible and necessary responses before they are properly integrated.

Similarly, Swagger allows for granular control of model visibility and information provision with the @ApiModel annotation. This annotation, along with @ApiModelProperty, allows you to specifically mark a model class for processing, preventing external information leak while providing adequate documentation:

@ApiModelpublic class User {private String userName;@ApiModelProperty(position = 1, required = true, value = "username containing only lowercase letters or numbers")public String getUserName() { return userName;}}

In this example, a String is defined for userName, and an @ApiModelProperty is used to specify the information that will be processed by the documentation engine, while allowing other variables to go undocumented.

Worthy of mention is the fact that Swagger, contrary to many documentation specifications, is designed as a bottom-up specification. Unlike other documentation specifications, which endeavor to explain the behavior formed by the API, Swagger specifies the behavior which affects the API in a bid to create more complex, interlocking systems.

Some may be deterred by the relatively increased complexity of documentation resulting from the increasing complexity of the system. All in all, Swagger’s feature set makes it a very popular choice, indeed, for APIs running across multiple platforms, environments, or revisions.

For more on system complexity: Balancing Complexity and Simplicity in API Design

(Video) Designing Quality APIs (Cloud Next '18)


Top Specification Formats for REST APIs | Nordic APIs | (4)RAML is a unique beast in the API documentation field, especially within the context of RESTful architectures. Because of the way RAML is designed, it can support REST API documentation in addition to documentation for APIs that don’t precisely or strictly adhere to REST standards such as those utilizing other design architectures like SOAP and RPC. This makes it a wonderful documentation language for languages that aren’t classically designed, or are designed to take advantage of the extensive modified frameworks available to API developers.

Fundamentally, RAML is still a REST-oriented documentation language. Much like Swagger, RAML is intimately related to YAML, but eschews JSON formatting in favor of YAML style text files, editable by any basic text editor or IDE. RAML is also a top-down specification, meaning that it breaks down the system and explains the behavior of the various sub-components.

RAML can be used in a variety of ways to extend its usefulness; because of how it’s defined and structured, it can be used both as documentation and as long-term planning for an API. The latter aspect makes RAML great for generating mock responses, planning function paths, or even implementing interactive API consoles.

Using RAML

RAML is very simple to use. Like Swagger, which has a required REST endpoint function, RAML requires certain metadata:

title: API1baseUri: https://api.provider.comprotocols: [ HTTP, HTTPS ]mediaType: application/json

By explicitly stating the above, we’re doing a few things. First, we’re establishing the title value and the baseUri as a means to identify the API being documented. This creates a “trackback” of sorts. Then, by defining the protocols and mediaType annotations, we’re specifying exactly the type of data that should be expected by the API developer or the user reviewing the API documentation.

We can then begin expressly describing the layout of the API itself. This format is unique to RAML, and is one of the many reasons it has become very popular.

/userrecords:get:description: Retrieve record of userspost:description: Create new user record/{isrc}:uriParameters: id: description: Internal record number for user IDstype: stringpattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$get:description: Retrieve user record by IDput:description: Update record by IDdelete:description: Delete this ID

Contrary to Swagger, which explains the functionality of an API through models and submodels, RAML specifically annotates and describes function methodology through nested resources and sub-resources. This, aesthetically, is far more oriented towards hierarchical function understanding than simple “cause and effect” understanding.

We can similarly state the response expectations and formation request standards using schema:

/userrecords:/{id}:get:description: Retrieve user record by IDresponses: 200: body: application/json: schema: | { "$schema": "", "type": "object", "description": “User ID", "properties": { "ID": { "type": "string" },"required": [ "id", “user” ] }example: | { "id": "90210","id": "90210","user": msmitts }}

Forgoing the complexity inherent in JSON formatting (which can be largely negated using an application which handles JSON format specifically), RAML is very much a hierarchical style format, which is one of the many reasons it is such an excellent planning tool. By visualizing the cause and effect of requests to the API, as well as documenting specific examples of what return can be expected, APIs can either be documented or planned with incredible granularity.

API Blueprint

Top Specification Formats for REST APIs | Nordic APIs | (5)So far, we’ve addressed two different styles of documentation that are largely two sides of the same coin — whereas RAML is strictly YAML in representation, Swagger is JSON with YAML compatibility. API Blueprint eschews this, however, with a dependence on Markdown as its format.

Like RAML, API Blueprint is a top-down specification. Whereas Swagger calls resources ‘operations’, API Blueprint describes them as ‘actions’. Unlike both RAML and Swagger, it requires third party server code, as it does not specify any of its own.

(Video) T-ResT: Automatic Test Framework for REST APIs from OpenAPI specification

Additionally, where RAML and Swagger are both utilizing Java and js to parse, API Blueprint specifically focuses on C++ through Node.js and C# implementations.

The main drawback? API Blueprint lacks advanced construct and code level tooling. Because of this, its adoption has been slow, dwarfed when compared to Swagger or RAML.

Using API Blueprint

Just as with any documentation specification, the name and metadata must first be established, which can be done simply with:

FORMAT: 1A# PollsPolls is a simple API allowing consumers to view polls and vote in them.

Resource groups and nested resources are then defined in plain text markdown:

# Group QuestionsResources related to questions in the API.## Question Collection [/questions]

Note that in markdown, “#” denotes a header, and “##” denotes a subheader. Here, we can see the obvious influence of markdown in both the structure and the thinking of the language — a Resource Group necessarily contains a Resource, just as a Header necessarily contains a Subheader.

Actions upon resources or resource groups can then be stated within those headings:

### List All Questions [GET]

We can see that API Blueprint is perhaps the easiest for newcomers to understand. Anybody who has ever written online, be it for a client or personal blog, likely has at least some basic Markdown experience — it’s instantly easy to understand and to read.

Read More: Using API Blueprint for Documentation Driven Design

Summation – Pros and Cons

So what is an API provider to do? With such great options, what does the choice come down to? From our study we can state the following objectively about these three API documentation specifications:


(Video) REST API and OpenAPI: It’s Not an Either/Or Question

  • Pros: Heavily adopted, large community of users and supporters, greater support for multiple languages
  • Cons: Lacks advanced constructs for metadata


  • Pros: Supports advanced constructs, decent adoption, human readable format, high industry backing
  • Cons: Lacks code-level tooling, still unproven long-term

API Blueprint

  • Pros: Easy to understand, simple to write
  • Cons: Low adoption, lacks advanced constructs in general, complex installation

The argument comes down to how you want to present your API documentation to your API developer users. Is readability most important? Is modern documentation and forward-thinking specification important? Do you care about adoption rates? These questions, along with their answers in the above pros and cons section, will inform your decision.

Likewise the specific languages and dependencies inherent in your service will be equally as important. If your API is dependent on complex class interactions that have hundreds of subsets and antecedent functions, a specification without advanced constructs is a poor choice, and vice versa.

There are, of course, alternatives. Two of the most popular are WADL and Slate. Each have their own caveats, of course.

WADL is incredibly time consuming to create descriptions with, and the linking methodology leaves much to be desired when compared to any of the three specifications discussed throughout this article.

Slate, similarly, has the caveat of having untested or unproven approaches due to the relatively small userbase, despite the fact that it handles documentation much like API Blueprint does, and generates a pretty interface for it all.

These alternatives are interesting, to be sure, but their low adoption rates, issues inherent to their structure, and fundamental caveats make a potentially unstable bet. With many strategies in the modern IT workforce focusing heavily on rapid development and deployment, untested approaches have the distinct possibility of massively lowered quality as the demand rises exponentially.

The methodology one chooses to document is important, but it is important to remember the way the API is designed will largely determine the success of the documentation itself. Think of it like any other language. English is not good simply because it is English — the greater industry of reality TV has shown that English can be equally used to educate and inspire as to push drivel.

Ultimately, the quality of the API will manifest itself in the quality of documentation — it is up to the developer to choose the specification that is appropriate to their work. An ultimately useful and functional API will manifest itself in proper documentation largely because of the amount of effort it takes to create such a well-rounded API; a poorly crafted API will, regardless of specification, almost always result in paired poor documentation.

For instance, with Swagger, SDK generation is baked into the system, with support for programming languages such as Go, Java, Groovy, PHP, Clojure, and more. If developing an SDK for client interaction is your end-goal, Swagger is your best choice. On the other hand, if SDK generation is handled via private or partner applications and methodologies, and larger adoption base is more important to you in the long run, RAML might be the specification of choice.

(Video) RESTful APIs in 100 Seconds // Build an API from Scratch with Node.js Express


A few developers have implemented language specific derivations of the Swagger documentation framework, supporting Scala, HTML5, Java, Actionscript 3, and others. The following resources can help you get started in understanding the various specification formats presented in this piece, as well as some deviations that are worth mention.

What documentation specification are you using? Why? Reach out to us on Twitter or comment below!


What is the most commonly accepted REST API specifications standard? ›

OpenAPI. OpenAPI is currently the most widely accepted format for REST API specifications. The specification is written in a single file in JSON or YAML format consisting of three sections: A header with the API name, description, and version, as well as any additional information.

Which data formats does REST API use? ›

The REST API supports the following data formats: application/json. application/json indicates JavaScript Object Notation (JSON) and is used for most of the resources. application/xml indicates eXtensible Markup Language (XML) and is used for selected resources.

In what format does a REST API typically respond with? ›

REST API Response

Data responses are typically JSON-encoded, but XML, CSV, simple strings, or any other format can be used.

What are the valid formats in which the API specifications can be written? ›

Direct data formats are best used when additional APIs or services require a data stream from your API in order to function. The three most common formats in this category are JSON, XML, and YAML.

What are the 4 most common REST API operations? ›

For REST APIs built on HTTP, the uniform interface includes using standard HTTP verbs to perform operations on resources. The most common operations are GET, POST, PUT, PATCH, and DELETE.

What are the standard API formats? ›

Today, there are three categories of API protocols or architectures: REST, RPC and SOAP. These might be dubbed "formats," each with unique characteristics and tradeoffs and employed for different purposes.

Which two API formats do REST APIs use? ›

REST APIs are based on URIs (Uniform Resource Identifier, of which a URL is a specific type) and the HTTP protocol and use JSON for a data format, which is super browser-compatible.

What are the two most common response formats for an API? ›

The most common formats found in modern APIs are JSON (JavaScript Object Notation) and XML (Extensible Markup Language).

What are the 3 principles for a RESTful API? ›

The only requirement is that they align to the following six REST design principles - also known as architectural constraints:
  • Uniform interface. ...
  • Client-server decoupling. ...
  • Statelessness. ...
  • Cacheability. ...
  • Layered system architecture. ...
  • Code on demand (optional).

What are three different data formats for APIs? ›

Data provided by APIs can be provided and consumed via different formats including JSON, XML, RSS, CSV Files, etc. NYU's best practice and default is to provide data in JSON format.

What is REST API specification? ›

An important standard to keep in mind as you design your own APIs is the OpenAPI specification. OpenAPI is a standard to describe REST APIs and it allows you to declare your API security method, design endpoints, request/response data, and HTTP status messages. Together, these define your API in a single document.

How do I write a good API specification? ›

How to write your First API Documentation
  1. Recognize the Audience. ...
  2. Create a User Journey Map. ...
  3. Start with Guidelines for Common Scenarios. ...
  4. Add Samples of Code. ...
  5. Call Out Error Messages and Status Codes. ...
  6. Maintain Your Documentation.
Oct 21, 2022

Which is the most popular format used in REST Web services? ›

JSON and XML REST data formats

The two most common data exchange formats are JSON and XML, and many RESTful web services can use both formats interchangeably, as long as the client can request the interaction to happen in either format.

Which is better SOAP XML or REST JSON? ›

REST allows a greater variety of data formats, whereas SOAP only allows XML. Coupled with JSON (which typically works better with data and offers faster parsing), REST is generally considered easier to work with. Thanks to JSON, REST offers better support for browser clients.

Can REST APIs use XML? ›

The REST API Client Service currently accepts only JSON input when making REST API Create, Read, Update, or Delete requests. It is nevertheless possible to use XML input when making REST API requests.

What are the 5 principles for a RESTful API? ›

Principles of Rest API
  • Client-Server decoupling. In a REST API design, client and server programs must be independent. ...
  • Uniform Interface. All API queries for the same resource should look the same regardless of where they come from. ...
  • Statelessness. ...
  • Layered System architecture. ...
  • Cacheable. ...
  • Code on Demand.
Jan 18, 2023

What are the 6 constraints of REST API? ›

The six architectural constraints of REST APIs
  • Client-server architecture. An API's job is to connect two pieces of software without limiting their own functionalities. ...
  • Statelessness. ...
  • Uniform Interface. ...
  • Layered system. ...
  • Cacheability. ...
  • Code on Demand.

What is the best API documentation? ›

9 Great API and Developer Documentation Examples
  • Plaid shows developers what's possible.
  • Render gets started quickly.
  • Twilio shares use cases.
  • APIMatic provides language-specific content.
  • Stripe makes it copy-paste easy.
  • SendGrid generates API references.
  • Dropbox lets developers interact with its API.
Sep 15, 2022

What is the modern specification for API? ›

Swagger or OpenAPI is a specification for describing RESTful APIs in an implementation language-agnostic manner. The resulting definition is human- and machine-readable. This makes it easy to build tools to generate documentation, client, and server stubs in various languages.

What is API spec file? ›

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including: Available endpoints ( /users ) and operations on each endpoint ( GET /users , POST /users ) Operation parameters Input and output for each operation.

What is the most common type of API? ›

REST, SOAP, and RPC are the most popular API architectures in use today — let's unpack each one in more detail.

What is the most common API? ›

The most common type of API is the web API, which can be accessed over the internet using HTTP. It's typically used with JavaScript to add features during web development. Other APIs include local APIs, mobile APIs, and machine-to-machine (M2M) APIs, but we'll be focusing on web APIs for now.

Which of the following is most common API format? ›

The most common formats found in modern APIs are JSON (JavaScript Object Notation) and XML (Extensible Markup Language).

What is the modern specification for describing a RESTful API? ›

Swagger or OpenAPI is a specification for describing RESTful APIs in an implementation language-agnostic manner. The resulting definition is human- and machine-readable. This makes it easy to build tools to generate documentation, client, and server stubs in various languages.


1. Introduction to Swagger API | OpenApi Specification | Swagger Tutorial - 1
(Code with Gokul)
2. APIs for Beginners 2023 - How to use an API (Full Course / Tutorial)
3. Open API Spec: The best way to document APIs | IUG 2021
4. 9 Best practices for designing REST APIs like a Pro (in 1 hr) | Node.js & Express | Beginners' guide
(AB Satyaprakash)
5. APIs for Beginners - How to use an API (Full Course / Tutorial)
6. Types of APIs That Every QA Should know | SOAP VS REST | 30 Days of API Testing | Day 11
(The Testing Academy)
Top Articles
Latest Posts
Article information

Author: Allyn Kozey

Last Updated: 07/10/2023

Views: 5271

Rating: 4.2 / 5 (63 voted)

Reviews: 86% of readers found this page helpful

Author information

Name: Allyn Kozey

Birthday: 1993-12-21

Address: Suite 454 40343 Larson Union, Port Melia, TX 16164

Phone: +2456904400762

Job: Investor Administrator

Hobby: Sketching, Puzzles, Pet, Mountaineering, Skydiving, Dowsing, Sports

Introduction: My name is Allyn Kozey, I am a outstanding, colorful, adventurous, encouraging, zealous, tender, helpful person who loves writing and wants to share my knowledge and understanding with you.