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.
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.
|Basic Information||Format||Markdown||YAML||JSON, YAML|
|Industry Backing||Apiary||Mulesoft, SOA, AngularJS, Intuit, Box, PayPal, & Programmable Web||3Scale, Apigee, Reverb|
|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”)|
|Representations (status codes, mime-types)||X||X||X|
|Authentication||Basic, Digest, Oauth, 1&2||Basic, API-Key, OAuth 2|
|Representation Metadata||<any> (inline)||<any> (inline/ external)||JSON Schema (subset)|
|Composition/ Inheritance||Resource Models||Traits, Resource Types|
|API Version metadata||X||X|
|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|
|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|
|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|
|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.
- 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!
My name is Hamza Ed-Douibi. I am a postdoctoral fellow working in the SOM Research Lab at the Internet Interdisciplinary Institute (IN3) of the Open University of Catalonia (UOC) in Barcelona.
Great article!!! Thank you
Thank you for the article. I found incorrect mention that swagger is only “Bottom-up” and Authoring is “3rd tarty”.
In fact swagger allows “top-down” approach out of the box and provides excellent online editor that can generate docs and code for your target language/framework.
A top-down approach where you would use the Swagger Editor to create your Swagger definition and then use the integrated Swagger Codegen tools to generate server implementation.
A bottom-up approach where you have an existing REST API for which you want to create a Swagger definition. Either you create the definition manually (using the same Swagger Editor mentioned above), or if you are using one of the supported frameworks (JAX-RS, node.js, etc), you can get the Swagger definition generated automatically for you. If you’re doing JAX-RS have a look at the example at https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X.
Thank you for reporting the mistake. The table has been corrected.
Again IT clowns reinvent the wheel!
First we had DOCUMENTATION. It’s not enough (or NIH), let’s make web services and WSDL. OK, a few years past, let’s make something new! Viola, we have absolutely same services, but now w/o description. And again somebody reinvent the wheel and brings that clumsy Swagger (even name is a spew!).
Thanks IT clowns we always have something to read/study/code, while they again scratch the ass to invent something new.
You could add to this list Restlet Studio, which has adopted RAML/OAS as a basis for API definitions.
Thanks Jeff for your comment,
In fact, this post covers only the specifications to define Web APIs such as Swagger (Open API), RAML and API Blueprint. Restlet Studio is a nice visual editor which allows users to create API definitions directly in the browser, generate swagger or Raml documents, and generate client SDKs (e.g. Android) or server skeletons (e.g. JAX-RS). As far as I know, Restlet Studio uses the specifications mentioned in the post but does not create a new one.
Hey Hamza, can you update the table to show in General Information that Apiary is supporting Swagger in beta mode now? Thanks!
RAML has tooling for .NET :
Thanks Hamza for the comparison. If you like a really top-down approach you can use the tool that we made to generate swagger from mindmappings. Mindmaps are easier to create with non-IT people. You have a free swagger when you sign up and I can arrange an extended free usage for you if you like the tool