Skip to content

Evolution of REST API Standards

This article goes through the evolution of REST API standards.

Pre-standard era of REST

REST is an architectural style. Roy Fielding introduced it in his PhD dissertation in 2000. In 2023, the main principles seem a pretty generic and obvious. Five of them:

  • client-server
  • stateless
  • cacheable
  • uniform interface
  • layered system

are something we nowadays take for granted. The sixth principle, code on demand, is the opposite. I have never come across any project, which would send code to the client and doubt it will ever be used in the future due to security reasons. When saying REST principles, I will refer to the first five.

If we implement an API according to REST principles, there's plenty of room for creativity. And that's what happened when REST APIs started to emerge. Flame wars started in which API is really RESTful and, more often, which is NOT. Once I read an article by one guy saying: "During my career, I have come across only a few really RESTful APIs. And, almost all of them were designed by myself." This humble statement illustrates the situation pretty well.

Actually, many developers loved this situation. They were frustrated by SOAP Web Services and their complicated standards. Switching to REST APIs was a relief: "Let's take HTTP and JSON, and here we go! Goodbye SOAP, goodbye WSDL, XML Schema and WS-* standards!" If you visit the previous link, you will probably understand.

Is REST a standard then?

REST is an architectural style. REST principles are too generic and broad to be a standard.

The need and the (surprising) winner

Of course, soon it was obvious REST APIs need some standards.

SOAP web services had WSDL; why not create something similar for REST APIs? And, WADL was here. Some tools have adopted WADL (SoapUI, Oracle SOA Suite, just to name few). A bit later, in 2013 RAML was proposed, RESTful API Modeling Language. RAML was backed by heavyweights in the integration space like MuleSoft, Cisco, VMWare and many others. RAML seemed promising. However, at the same time, Tony Tam came up with Swagger, to help with API design and documentation for his Wordnik project. Tony Tam released Swagger as an open-source project. Later, Smartbear company took over Swagger and renamed it to OpenAPI, set up the OpenAPI Initiative and published it as a standard backed by Linux Foundation.

WADL, RAML, API Blueprint, and OpenAPI have some differences, but serve the same purpose. You can convert from one to another, e.g. with APIMatic tool.

However, OpenAPI became the winner. Nowadays, it is by far the most popular standard for REST API design.