Modeling Web APIs: your best choices

Tweet about this on TwitterShare on FacebookBuffer this pageShare on RedditShare on LinkedInShare on Google+Email this to someone

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 API-Designer Swagger Editor
Ad-hoc testing 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!


Tweet about this on TwitterShare on FacebookBuffer this pageShare on RedditShare on LinkedInShare on Google+Email this to someone
  1. Ved
  2. user
    • Hamza Ed-douibi
  3. Thorn
  4. Jeff M Lowery
    • Hamza Ed-douibi
  5. Romina


Your email address will not be published. Required fields are marked *