Nowadays everything involving web development seems to revolve around Web APIs and related concepts like Swagger, RAML, REST…  But do we really understand what is a Web API and the relationship between Web API and REST? Or even where does Swagger fit into all of this?

This blog post aims to

• provide some clear definitions linking these different concepts
• explain why you need to take the time to model / describe your web APIs
• present and compare a few languages to do so

 

API & Web APIs

An API (Application Programming Interface) is the interface for a client to interact with a system. For instance, The Java Persistence API (JPA) provides Java developers with an object/relational mapping facility for managing relational data in Java application regardless of the underlying database. The developer only needs to care about how the interface works while the implementation itself is left to a provider e.g., Hibernate and EclipseLink implementing the API.

In the case of JPA, invoking the API is done locally (by annotating POJOs, using the query language,…). For other cases, the API can also be exposed for remote access (Internet; or a local network for example). In this case, you need to define a system for interprocess communication or what we call a Web service.

W3C defines a Web service as a software system designed to support interoperable machine-to-machine interaction over a network. Technically, the term Web service describes a way of integrating Web-based applications using the standards XML, SOAP, WSDL and UDDI over an Internet protocol framework. In 2004, W3C extended the definition to add a new class of Web services called REST-compliant Web services, in which the primary purpose of the service is to manipulate representations of Web resources using a uniform set of “stateless operations”.

We can then define Web APIs as APIs offering one or more publicly exposed endpoints to a defined request-response message system (typically expressed in JSON or XML)  for either a Web server or a Web browser. You can check ProgrammableWeb (a registry of Web APIs) for some interesting statistics regarding the growth of REST APIs since 2005.

The importance of modeling /documenting Web RESTful APIs

The more you describe your APIs the better both for human and machine consumption. Just some unstructed text manualy written in English (or any other natural language) in your website will not do it since only humans will be able to understand it (and only after investing too much time  on it).

And using “traditional” web services approaches for documenting (RESTful) APIs are not a great idea either, though there is an attempt to do exactly that. Same as web services come with a WSDL (Web Service Description Language) description,  specifying a contract between the provider and the consumer of the service, a schema called WADL (Web Application Description Language) has been proposed for REST services / APIs. Even if WSDL could be used for that, WADL is intended to simplify the process for the specific case of REST services.

Still, a WADL is a machine-readable XML  description of http-based web applications not suitable for developers trying to get an idea of how to use the API (or whether the API could fit their needs).

This situation (not having a good format for both humans and machines) have triggered the creation of frameworks and languages to describe Web APIs in a way that everybody can understand. Below is an overview of some of these frameworks (in alphabetical order) and a comparison among three of them at the end.

API Blueprint is a documentation-oriented web API description language. The API Blueprint is essentially a set of semantic assumptions laid on top of the Markdown syntax used to describe a web API. Using API Blueprint gives you tools for your whole API lifecycle. It can be used to discuss your API with others, generate documentation automatically, or a test suite.

IO Docs is a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface. API calls can be executed from this interface, which are then proxied through the I/O Docs server with payload data cleanly formatted (pretty-printed if JSON or XML). Basic HTML text tags are enabled in the JSON schema.

RAML (RESTful API Modeling Language) is a YAML-based language for describing RESTful APIs. It provides all the information necessary to describe RESTful or practically-RESTful APIs. Although designed with RESTful APIs in mind, RAML is capable of describing APIs that do not obey all constraints of REST (hence the description “practically-RESTful”). It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices.

Slate allows you to write your API documentation using markdown, which Slate will then package up as a pre-styled static HTML site for you. Because it generates static HTML, hosting is straightforward – in particular, it’s a breeze to host with Github Pages.

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. Applications implemented with the Swagger framework contain documentation of methods, parameters and models directly in their source code. This prevents the situation when the documentation, client libraries, and source code get out of sync. The overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server.

Comparing  API Blueprint vs RAML vs Swagger 

Choosing one of the previous languages depends on your needs and on what you are expecting from the chosen framework. For example, the criteria could be the accessibility of the framework, the tooling (e.g. can I generate tests for the API?), the supported platform (e.g. if I work with JEE, can I generate JAX-RS resources directly from the documentation?), the metadata level (does is support the QoS metadata that I might need?), …

To help you with some questions, we combined in the table below some information from the official documentation of the chosen APIs  and the references mentioned at the end of this post.

		API Blueprint	RAML	Swagger
Basic Information	Format	Markdown	YAML	JSON, YAML
	Available at	GitHub	GitHub	GitHub
	Industry Backing	Apiary	Mulesoft, SOA, AngularJS, Intuit, Box, PayPal, & Programmable Web	3Scale, Apigee, Reverb
	Current Version	1A9	1.0	2.0
	Workgroup	No	Yes	Yes
	Initial commit	April 2013	September 2013	July 2011
	API Design Approach	Top-down	Top-down	Top-down, Bottom-up (for the supported frameworks)
REST Modeling	Resources	X	X	X (“api”)
	Methods/ Actions	X (“action”)	X (“method”)	X (“operation”)
	Query Parameters	X	X	X
	Path/URL Parameters	X	X	X
	Header Parameters	X	X	X
	Representations (status codes, mime-types)	X	X	X
	Documentation	X	X	X
	Authentication		Basic, Digest, Oauth, 1&2	Basic, API-Key, OAuth 2
	Representation Metadata	<any> (inline)	<any> (inline/ external)	JSON Schema (subset)
	Nested Resources	X	X
	Composition/ Inheritance	Resource Models	Traits, Resource Types
	File inclusions		X
	API Version metadata		X	X
	Sample Representations	X	X
Tooling	Authoring	apiary.io	API-Designer	Swagger Editor
	Ad-hoc testing	apiary.io	API-Console	Swagger-UI
	API Console	Unknown	Grouped by endpoint with drill down into verbs	Every HTTP Action Verb is separate
	API Builder	Node & .Net bindings	MuleStudio APIKit (Visual, drag and drop), Osprey (Node)	Tools for most popular languages
	Documentation Builder	Single or multiple page documentation builder	Single or multiple page documentation builder (PHP only)	Single page documentation builder
	Mocking	X	X	(3rd party)
	Server Code	(3rd party)	Java	Java, scala, ruby, node.js
	Generate from code			Java, 3rd party (go, python)
	Language Support	Node, .Net	JS, Java, Node, PHP, Python, Ruby	Clojure, Go, JS, Java, .Net, Node, PHP, Python, Ruby, Scala
	Validation	X	X (java)	X
	Parsing	C++ (nodejs, c#)	Java, js	Java, js
	Easy of Getting Started	Installation required	Very easy, everything in Github repos	Very easy, everything in Github repos
Community stats (Dec. 2015)	Stackoverflow questions	696	288	3181
	GitHub Stars	3002	391	3773
	GitHub contributors	38	26	114
	GitHub whatchers	147	154	276
	GitHub forks	872	118	2196
	Google search (name + “rest”)	350K	85K	733K
Summary	Pros	Good online design tools, good community involvement, easy to understand, simple to write	Good online design tools and mature supporting infrastructure, seemingly useful advanced constructs, human readable format, hight industry backing	High adoption rate, good code-level tooling, large and active community of users and supporters, greater support for multiple languages
	Cons	New to the game, low adoption, lacks advanced constructs and code-level tooling, complex installation	Very new to the game, low adoption, lacks code-level tooling, still unproven long-term	lacks advanced constructs for metadata

The Open API Initiative

Recently, we have also some good news on this topic. Several APIs contributors (members of 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, Restlet and SmartBear) have announced the Open API Initiative, which aims at standardizing the way REST APIs are described.

This initiative will extend the Swagger specification and format to create an open technical community where members can easily contribute to building a vendor neutral, portable and open specification for providing metadata for RESTful APIs. We hope this initiative will also promote and facilitate the adoption and use of a standard API Description Language.

Additional resources

• A nice graphical comparison regarding the specs of some  languages could be found here
• RAML vs. Swagger vs. API Blueprint : A blog post comparing the three frameworks a choosing a winner following one criteria. However the old version of Swagger is used. (July 2014).
• Top Specification Formats for REST APIs : A nice blog post about specification formats of RAML, Swagger an API Blueprint with examples (September 2015).
• API Description Languages (August 2014)
• Here is a nice read if you want to model REST APIs. This E-book by Apigee gives the best practices to follow while designing a REST API. It also provides some tips regarding APIs monitoring. Don’t miss to read it!