API Description Languages: Which is the Right One for Me?

Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
API Description Languages:
Which is the right one for me?
Laura Heritage
Director of API Strategy

What is an API Description Language (API DL)?
Contract Human DocsMetadataBlueprint

API DL Brings REST to the Enterprise
“Lack of a way to describe a RESTful services was one of the
largest barriers to REST adoption in the enterprise.”
Governable ReadableShareable

Many API DL Are Available Today
Hypermedia

What About WSDL2.0 or WADL?
• For REST, they are not widely adopted
• Both are not very “humanly readable”
• Both are typically auto-generate from code – wouldn’t use
them as a “blueprint” amongst non-technical types
• WADL doesn’t contain enough information to adequately
describe a RESTful API. Though does have extension points
which are seldom used.
• WSDL contains almost everything you need but is quite
brittle. If it changes the clients must change too

What About HyperMedia?
HAL
Siren
Collection+JSON
JSON-LD
JsonAPI
Mason
UBER
Odata

Are We Ready For Hypermedia?
http://www.infoq.com/articles/implementing-hypermedia
“While much of the theory of hypermedia talks about hypermedia
as the fundamental, underlying theory of your entire API, I have a
little secret to share with you: it doesn't have to be that way. You
can gain some of the advantages of hypermedia without doing an
entire overhaul of your API” – Steve Klabnik

Most Active API DL Communities
API-Blueprint RAML* SWAGGER 2.0
(1.2)*
Format Markdown YAML JSON
(YAML Editor provided by 3rd
party with 2.0)
Available at GitHub GitHub GitHub
Sponsored by Apiary Mulesoft Reverb
Current Version 1A3 0.8 2.0
Workgroup No Yes Yes
Initial commit April, 2013 Sep, 2013 July, 2011 (Sept,
2014)
API Design
Approach
Top-down Top-down **Bottom-up
* Most Widely Adopted by Enterprises

How Do You Choose?

Define Key Purpose Behind Using an API DL
Swagger
R 1.2
Swagger
2.0
RAML API Blueprint
I need to generate
documentation from my
existing REST based APIS
X X X -
I need the ability to design the
API with non-super techie API
stakeholders
- X X X
I want a way to describe and
design an API with my technical
team
X X X X
I need to easily consume the
API specification between two
or more systems
X X X X
I need exceptional external API
developer experiences
X X X Markdown

Core Capabilities Needed
SWAGGE
R 1.2
Swagger
2.0
RAML API Blueprint
I need to validate the requests
and responses at runtime
X
(swagger-node-
express,
swagger -Play)
X X
(Osprey)
-
I need to easily consume the
API specification between two
or more systems
X X X limited
I am an enterprise and want a
standard canonical model
across the enterprise
- limited X limited
I need support for XML - limited X -
I need ability to Mock X X X X
I need to generate server code X X X X
I need to generate client code X X X -
I need to unit Test against the
spec
X X X X

Look At Their Community
• Swagger by far has the largest community, since its been around since 2011
• RAML has gained traction in the enterprise due to the richness of its modeling
capability; API version metatdata, nested resources, composition and inheritance, file
inclusions and top down approach
• API Blueprint is up and coming.
Generators
SWAGGER RAML API Blueprint
Documentation From
Code
Clojure,
ColdFusion/CFML,
Eiffel, Go, Java,
.Net, Node.js, PHP,
Python, Ruby, Scala
JAX-RS Not from code but HTTP
Requests.
cURL trace parser
Rspect API Blueprint
Spec Parsers Java, node.js PHP, Ruby, Phython,
Java, Javascript
Node, Ruby, .Net
Client Code Several Developing Developing
Editor Tooling Swagger Editor
(YAML based)
API Designer, Sublime
plugin, Atom
Apiary.io, Sublime, Any
markdown editor

Does One API-DL Fit an Entire Enterprise?
• What is your teams development style?

Understand How Your Team Works
SWAGGE
R
1.2
SWAGGE
R 2.0
RAML API
Blueprint
Do you design
before you code?
- X X X
Do you generate
documents after you
code from your
code?
X X X -
Do you want docs
embedded in your
server code?
X X - -

RAML
Start with tutorial at RAML.org

RAML Editors
• API Designer - http://api-
portal.anypoint.mulesoft.com/raml/api-designer
– (allows for mocking)
• Sublime Editor
https://github.com/mulesoft/raml-sublime-
plugin
• Can have 1 to many files
• I have a very simple API.
I kept mine in 1. Didn’t
use includes, but did play
with them

Document Generation
• RAML to HTML
• RAML to HTML - PHP

Thoughts on RAML Experience
• Great documentation, samples and tutorial
• Good way to model your API
– When writing my server code, I did find I went back to my RAML model to
remember what I was suppose to be doing.
• You can generate JAX-RS code
• It is easy to understand and write, from the basic API perspective.
– When you get into Includes, Traits, it becomes a little more technical.
• Good way to enforce design standards for your APIs
• Community tools
– Are easy to understand, install and work with.
– I played with:
• API Designer
• RAML Sublime Plugin
• RAML to HTML
• Swagger2raml
• Osprey / Osprey CLI

SWAGGER http://swagger.io

Three Ways To Create Swagger Docs
1. Codegen: Traditional way of creating a Swagger Specification.
The swagger codegen converts annotation in your code to
Swagger Specification
2. Automatically: swagger-node-express and swagger-play will
create both your REST APIs and your Swagger Specification for
you at the same time
– https://www.npmjs.org/package/swagger-node-express
3. Manually: Write the json by hand.
4. NEW - Swagger Editor

Used swagger-node-express
• Server.js – the node-
express server
• Model.js - describes
the resources (User,
Wish)
• Routes.js – defines the
routes for data access
logic
Spec
Action

Swagger Editor
• Available both
online and to
download

Swagger Documentation
Swagger 1.2 is composed of two files:
• Resource Listing: Lists the APIs that are available and gives a brief description of the them.
• API Description: Detailed description of each API in the Resource Listing.
• No ability to split out
Swagger 2.0 reduced this to one file with ability to split parts of the definition
out into separate files.

Thoughts on SWAGGER Experience
• Most widely used API DL to date, mostly generated from code
• Swagger-core project provides nice examples on how to build a Swagger
enabled server using java-jaxrs, scala-jaxrs and more.
• Swagger-UI is very useful to help visualize and test your API
• If you have complex APIs, swagger probably won’t have the the
constructs you need to fully express them.
• Writing swagger manually in JSON is not fun. It is not very human
readable.
• A new Swagger Editor project based on YAML was launched in May is very
nice.
• On working with swagger-node-express:
– Fast way to prototype and API
– Once you get the hang of it, went smooth and very fun to see results.
– Key is to get your model.js (resource definitions) and your routes.js for your
data access specified correctly.
– Definitely not top down. I ended up using my RAML spec to keep me on track.
– Con - you are really embedding swagger throughout your code. Code which
may live forever.

APIBlueprint.org

APIBlueprint Editors
• Apiary.io
http://apiary.io
– allows for mocking
• Sublime Editor
https://github.com/apiaryio/api-blueprint-sublime-plugin

Thought on APIBlueprint
• Good for rapid prototyping and testing of an API
• Really non-techie readable due to markdown
• Because of markdown, easily read by any markdown
viewer. Github ready, so to say.
• Not as easy to get the sublime plugin installed.
– Didn’t manage to get it working yet
• Not as big of following in the enterprise as swagger and
raml… yet..

Thoughts On the API DL Focused on Today
• All the API DL are starting to provide similar features and functions. They will
continue to get closer and closer.
• All are extremely painful when your API is large and you get “off” on your
markdown, YAML or JSON.
• None of the specifications that we focused on today can describe anything
other then a RESTful API/Service.
– For SOAP based APIs WSDL is still king. An API Platform you choose should support
SOAP based APIs via WSDL as well.
• None of the specifications provides ability for extension, for example:
describing testing and monitoring of the operations
– Swagger 2.0 has added the capability to provide extensions
• None of the specifications handles National Language (NLS) of documentation
• System to System interactions – Today mostly focused on API creation and
developer consumption. Next step is for system-to-system integrations

The SOA Software Digital Business Platform

API Resources and API University
• Resource Center
– http://resource.soa.com/
• Follow us on:
www.facebook.com/soasoftware
www.linkedin.com/company/soasoftware
@soasoftwareinc

Questions

References
• Another API-Blueprint, RAML, Swagger Comparison – Ole
Lensmar
• Investigating API Developer Tooling - @DanMayer

API Description Languages: Which is the Right One for Me?

Recommended

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to API Description Languages: Which is the Right One for Me? (20)

More from Akana (18)

Recently uploaded (19)

API Description Languages: Which is the Right One for Me?

Editor's Notes