API Description Languages

Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
API Description Languages!
Laura Heritage!
Director of API Strategy!

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

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

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

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

How Do You Choose?!

Deﬁne Key Purpose Behind Using an API DL!
SWAGGER RAML
I need the ability to design the API with technically limited API
stakeholders
-
(new top down tooling
being developed)
X
I want a way to describe and design an API with my technical
team
X X
(has more advanced
meta data constructs
(includes, inheritance,
traits))
I need to validate the requests and responses at runtime X
(swagger-node-
express, swagger -
Play)
X
(Osprey)
I need to easily consume the API specification between two or
more systems
X X
I need documentation for audit and compliance X X
I need exceptional external API developer experiences X X
I need to generate server code X
(node.js, Java)
X
(node.js, Java)
I need to generate client code X limited

Understand How Your Team Works!
SWAGGER RAML
Do you design before you
code?
- X
Do you generate documents
after you code from your
code?
X X
(early release of JAXRS-to-
RAML)
Do you want docs embedded
in your server code?
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
Generators
SWAGGER RAML
Documentation From Code Clojure, ColdFusion/CFML,
Eiffel, Go, Java, .Net,
Node.js, PHP, Python,
Ruby, Scala
JAX-RS
Spec Parsers Java, js PHP, Ruby, Phython, Java,
Javascript
API Interfaces Java, Node.js Java, Node.js
Client Code Several Developing
Editor Tooling *new in the works based
on YAML, demo’d in May
API Designer, Sublime plugin,
Atom

In Action – What Is the Experience?!
•  WishList Application
–  Add a User
–  Get Users
–  Add a wish
–  Get all wishes in the system
–  Get wishes for particular user
•  Filter by price range
•  Filter by merchant
•  Platform : Node.js, Express and Mongo
•  Test
–  Build with RAML
–  Build with SWAGGER Reese’s Birthday Soon

My Background !
•  Degree in Computer Science & Mathematic
•  16 years @IBM and 5 Months at @SOASoftwareInc
•  14+ years working with SOAP/REST, SOA, API
•  Over the years I have been a developer, an architect, a
competitive technical sales, a product manager and an
evangelist
•  I always liked to be on the bleeding of edge technology
•  Very hands on
•  I would consider myself a “Sunday” developer. I don’t get to
code as often as I use to. Now I mostly configure products
and do scripting.
•  Spend most of my time working with customer.

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
NOTE: Indentation matters in both
•  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
•  No Security

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.
•  It is easy to understand and write, from the basic API perspective.
–  When you get into Includes, Traits, it becomes a little more technical.
•  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!
Swagger Community
•  https://github.com/wordnik/swagger-spec
Swagger Getting Started
•  https://github.com/wordnik/swagger-spec/wiki

Three Ways To Create Swagger!
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.

Used swagger-node-express!
•  Server.js – the node-
express server
•  Model.js - describes
the resources (User,
Wish)
•  Resource.js – defines
the actions for the
resources
Spec
Action

Swagger Documentation!
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.

Thoughts on SWAGGER Experience!
•  Most widely used API DL to date
•  On working with swagger-node-express:
–  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, but will swagger?
•  On Codegen creation of swagger:
–  Easy self-explanatory
–  Is still a bottom up approach. Even though you are stubbing out your code as
you are modeling it, it is hard to share and express thoughts with out a lot of
effort up front.
•  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 was launched in May.

Where to do documentation?!
Pros Cons
Document in design and
generate interface and docs
from design
•  Allows for changing docs
without disturbing
production code.
•  Allows for NLS translation
outside of production cycles
•  If backend implementation
changes but interface still
the same, you are okay.
Documentation can get out of
sync with what is running in
production.
Document in code and
generate docs from code
•  Documentation is more
likely to stay in sync with
what is in production
•  If issues with
documentation, need to
edit production code to
regenerate
Embed documentation in
server code and have server
dynamically serve up docs
•  Documentation is more
likely to stay in sync
because it is embedded and
running as part of the
application
•  You are now tied to that
particular API DL
implementation running
your production code
•  If there is user
documentation errors,
production changes are a
must

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.
•  Neither 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.
•  Neither specification provides ability for extension, for example:
describing testing and monitoring of the operations
•  Neither specification 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

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

Questions!

API Description Languages

More Related Content

What's hot (20)

Similar to API Description Languages (20)

More from Akana (20)

Recently uploaded (20)

API Description Languages