SlideShare a Scribd company logo
1 of 25
Download to read offline
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
API Description Languages!
Laura Heritage!
Director of API Strategy!
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
What is an API Description Language (API DL)?!
Contract Human DocsMetadataBlueprint
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
Many API DL Are Available Today!
Hypermedia
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
How Do You Choose?!
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
Define 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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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 -
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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.
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
RAML!
Start with tutorial at RAML.org
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
Document Generation!
•  RAML to HTML
•  RAML to HTML - PHP
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
SWAGGER!
Swagger Community
•  https://github.com/wordnik/swagger-spec
Swagger Getting Started
•  https://github.com/wordnik/swagger-spec/wiki
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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.
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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.
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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.
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
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
Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved.
References!
•  Another API-Blueprint, RAML, Swagger Comparison – Ole
Lensmar
•  Investigating API Developer Tooling - @DanMayer
Copyright © 2001-2014 SOA Software, Inc. All Rights Reserved.
Questions!

More Related Content

What's hot

API Strategy Presentation
API Strategy PresentationAPI Strategy Presentation
API Strategy PresentationLawrence Coburn
 
Architecting an Enterprise API Management Strategy
Architecting an Enterprise API Management StrategyArchitecting an Enterprise API Management Strategy
Architecting an Enterprise API Management StrategyWSO2
 
Designing APIs with OpenAPI Spec
Designing APIs with OpenAPI SpecDesigning APIs with OpenAPI Spec
Designing APIs with OpenAPI SpecAdam Paxton
 
Test Design and Automation for REST API
Test Design and Automation for REST APITest Design and Automation for REST API
Test Design and Automation for REST APIIvan Katunou
 
Postman: An Introduction for Developers
Postman: An Introduction for DevelopersPostman: An Introduction for Developers
Postman: An Introduction for DevelopersPostman
 
Test in Rest. API testing with the help of Rest Assured.
Test in Rest. API testing with the help of  Rest Assured.Test in Rest. API testing with the help of  Rest Assured.
Test in Rest. API testing with the help of Rest Assured.Artem Korchevyi
 
API Strategy Introduction
API Strategy IntroductionAPI Strategy Introduction
API Strategy IntroductionDoug Gregory
 
API Management in Digital Transformation
API Management in Digital TransformationAPI Management in Digital Transformation
API Management in Digital TransformationAditya Thatte
 
Build your APPs in Lean and Agile Way using AWS Amplify
Build your APPs in Lean and Agile Way using AWS AmplifyBuild your APPs in Lean and Agile Way using AWS Amplify
Build your APPs in Lean and Agile Way using AWS AmplifyAmazon Web Services
 
Apex Enterprise Patterns: Building Strong Foundations
Apex Enterprise Patterns: Building Strong FoundationsApex Enterprise Patterns: Building Strong Foundations
Apex Enterprise Patterns: Building Strong FoundationsSalesforce Developers
 
API Testing: The heart of functional testing" with Bj Rollison
API Testing: The heart of functional testing" with Bj RollisonAPI Testing: The heart of functional testing" with Bj Rollison
API Testing: The heart of functional testing" with Bj RollisonTEST Huddle
 
What is API - Understanding API Simplified
What is API - Understanding API SimplifiedWhat is API - Understanding API Simplified
What is API - Understanding API SimplifiedJubin Aghara
 

What's hot (20)

API Strategy Presentation
API Strategy PresentationAPI Strategy Presentation
API Strategy Presentation
 
Architecting an Enterprise API Management Strategy
Architecting an Enterprise API Management StrategyArchitecting an Enterprise API Management Strategy
Architecting an Enterprise API Management Strategy
 
Designing APIs with OpenAPI Spec
Designing APIs with OpenAPI SpecDesigning APIs with OpenAPI Spec
Designing APIs with OpenAPI Spec
 
Test Design and Automation for REST API
Test Design and Automation for REST APITest Design and Automation for REST API
Test Design and Automation for REST API
 
Amazon API Gateway
Amazon API GatewayAmazon API Gateway
Amazon API Gateway
 
Postman: An Introduction for Developers
Postman: An Introduction for DevelopersPostman: An Introduction for Developers
Postman: An Introduction for Developers
 
Test in Rest. API testing with the help of Rest Assured.
Test in Rest. API testing with the help of  Rest Assured.Test in Rest. API testing with the help of  Rest Assured.
Test in Rest. API testing with the help of Rest Assured.
 
Introduction to Serverless
Introduction to ServerlessIntroduction to Serverless
Introduction to Serverless
 
API Strategy Introduction
API Strategy IntroductionAPI Strategy Introduction
API Strategy Introduction
 
API Management in Digital Transformation
API Management in Digital TransformationAPI Management in Digital Transformation
API Management in Digital Transformation
 
Build your APPs in Lean and Agile Way using AWS Amplify
Build your APPs in Lean and Agile Way using AWS AmplifyBuild your APPs in Lean and Agile Way using AWS Amplify
Build your APPs in Lean and Agile Way using AWS Amplify
 
Apex Enterprise Patterns: Building Strong Foundations
Apex Enterprise Patterns: Building Strong FoundationsApex Enterprise Patterns: Building Strong Foundations
Apex Enterprise Patterns: Building Strong Foundations
 
API Testing: The heart of functional testing" with Bj Rollison
API Testing: The heart of functional testing" with Bj RollisonAPI Testing: The heart of functional testing" with Bj Rollison
API Testing: The heart of functional testing" with Bj Rollison
 
API for Beginners
API for BeginnersAPI for Beginners
API for Beginners
 
Rest assured
Rest assuredRest assured
Rest assured
 
Rest API
Rest APIRest API
Rest API
 
Belajar Postman test runner
Belajar Postman test runnerBelajar Postman test runner
Belajar Postman test runner
 
Postman.ppt
Postman.pptPostman.ppt
Postman.ppt
 
What is API - Understanding API Simplified
What is API - Understanding API SimplifiedWhat is API - Understanding API Simplified
What is API - Understanding API Simplified
 
API
APIAPI
API
 

Viewers also liked

Another API-Blueprint, RAML and Swagger Comparison
Another API-Blueprint, RAML and Swagger ComparisonAnother API-Blueprint, RAML and Swagger Comparison
Another API-Blueprint, RAML and Swagger ComparisonSmartBear
 
Design Driven API Development
Design Driven API DevelopmentDesign Driven API Development
Design Driven API DevelopmentSokichi Fujita
 
Ultimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation SolutionsUltimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation SolutionsBill Doerrfeld
 
API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?Akana
 
API Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rantAPI Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rantVladimir Shulyak
 
Is it time for a Connector-less Approach to Cloud Integration?
Is it time for a Connector-less Approach to Cloud Integration? Is it time for a Connector-less Approach to Cloud Integration?
Is it time for a Connector-less Approach to Cloud Integration? Akana
 
Platform for Secure Digital Business
Platform for Secure Digital BusinessPlatform for Secure Digital Business
Platform for Secure Digital BusinessAkana
 
Realizing SOA and API Convergence
Realizing SOA and API ConvergenceRealizing SOA and API Convergence
Realizing SOA and API ConvergenceAkana
 
Powering Internal API Communities
Powering Internal API CommunitiesPowering Internal API Communities
Powering Internal API CommunitiesAkana
 
Manage Your Mesh
Manage Your MeshManage Your Mesh
Manage Your MeshAkana
 
API Frenzy: API Strategy 101
API Frenzy: API Strategy 101API Frenzy: API Strategy 101
API Frenzy: API Strategy 101Akana
 
Introducing Bonsai
Introducing BonsaiIntroducing Bonsai
Introducing BonsaiBen Schwarz
 
Generating the mule flow as html document
Generating the mule flow as html documentGenerating the mule flow as html document
Generating the mule flow as html documentprudhvivreddy
 
What is Mule ESB
What is Mule ESB What is Mule ESB
What is Mule ESB Nam Le Dinh
 
PiterPy 2016: Parallelization, Aggregation and Validation of API in Python
PiterPy 2016: Parallelization, Aggregation and Validation of API in PythonPiterPy 2016: Parallelization, Aggregation and Validation of API in Python
PiterPy 2016: Parallelization, Aggregation and Validation of API in PythonMax Klymyshyn
 
Smart Gamification
Smart GamificationSmart Gamification
Smart GamificationAmy Jo Kim
 
Getting Developers hooked on your API by Nicolas Garnier at Codemotion Dubai
Getting Developers hooked on your API by Nicolas Garnier at Codemotion DubaiGetting Developers hooked on your API by Nicolas Garnier at Codemotion Dubai
Getting Developers hooked on your API by Nicolas Garnier at Codemotion DubaiCodemotion Dubai
 
オープンイノベーション事例 アップル
オープンイノベーション事例 アップルオープンイノベーション事例 アップル
オープンイノベーション事例 アップルTakayuki Yamazaki
 
Lamdba micro service using Amazon Api Gateway
Lamdba micro service using Amazon Api GatewayLamdba micro service using Amazon Api Gateway
Lamdba micro service using Amazon Api GatewayMike Becker
 

Viewers also liked (20)

Another API-Blueprint, RAML and Swagger Comparison
Another API-Blueprint, RAML and Swagger ComparisonAnother API-Blueprint, RAML and Swagger Comparison
Another API-Blueprint, RAML and Swagger Comparison
 
Design Driven API Development
Design Driven API DevelopmentDesign Driven API Development
Design Driven API Development
 
Ultimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation SolutionsUltimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation Solutions
 
API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?
 
API Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rantAPI Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rant
 
Is it time for a Connector-less Approach to Cloud Integration?
Is it time for a Connector-less Approach to Cloud Integration? Is it time for a Connector-less Approach to Cloud Integration?
Is it time for a Connector-less Approach to Cloud Integration?
 
Platform for Secure Digital Business
Platform for Secure Digital BusinessPlatform for Secure Digital Business
Platform for Secure Digital Business
 
Realizing SOA and API Convergence
Realizing SOA and API ConvergenceRealizing SOA and API Convergence
Realizing SOA and API Convergence
 
Powering Internal API Communities
Powering Internal API CommunitiesPowering Internal API Communities
Powering Internal API Communities
 
Manage Your Mesh
Manage Your MeshManage Your Mesh
Manage Your Mesh
 
API Frenzy: API Strategy 101
API Frenzy: API Strategy 101API Frenzy: API Strategy 101
API Frenzy: API Strategy 101
 
Introducing Bonsai
Introducing BonsaiIntroducing Bonsai
Introducing Bonsai
 
Generating the mule flow as html document
Generating the mule flow as html documentGenerating the mule flow as html document
Generating the mule flow as html document
 
What is Mule ESB
What is Mule ESB What is Mule ESB
What is Mule ESB
 
PiterPy 2016: Parallelization, Aggregation and Validation of API in Python
PiterPy 2016: Parallelization, Aggregation and Validation of API in PythonPiterPy 2016: Parallelization, Aggregation and Validation of API in Python
PiterPy 2016: Parallelization, Aggregation and Validation of API in Python
 
Smart Gamification
Smart GamificationSmart Gamification
Smart Gamification
 
Getting Developers hooked on your API by Nicolas Garnier at Codemotion Dubai
Getting Developers hooked on your API by Nicolas Garnier at Codemotion DubaiGetting Developers hooked on your API by Nicolas Garnier at Codemotion Dubai
Getting Developers hooked on your API by Nicolas Garnier at Codemotion Dubai
 
VRとWeb API
VRとWeb APIVRとWeb API
VRとWeb API
 
オープンイノベーション事例 アップル
オープンイノベーション事例 アップルオープンイノベーション事例 アップル
オープンイノベーション事例 アップル
 
Lamdba micro service using Amazon Api Gateway
Lamdba micro service using Amazon Api GatewayLamdba micro service using Amazon Api Gateway
Lamdba micro service using Amazon Api Gateway
 

Similar to API Description Languages

API Description Languages: Which Is The Right One For Me?
 API Description Languages: Which Is The Right One For Me?  API Description Languages: Which Is The Right One For Me?
API Description Languages: Which Is The Right One For Me? ProgrammableWeb
 
API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?Akana
 
Rest api design by george reese
Rest api design by george reeseRest api design by george reese
Rest api design by george reesebuildacloud
 
Punta Dreamin 17 Generic Apex and Tooling Api
Punta Dreamin 17 Generic Apex and Tooling ApiPunta Dreamin 17 Generic Apex and Tooling Api
Punta Dreamin 17 Generic Apex and Tooling ApiAdam Olshansky
 
Building a REST API for Longevity
Building a REST API for LongevityBuilding a REST API for Longevity
Building a REST API for LongevityMuleSoft
 
Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)Tony Tam
 
Are APIs and SOA Converging?
Are APIs and SOA Converging?Are APIs and SOA Converging?
Are APIs and SOA Converging?Akana
 
Are APIs and SOA Converging?
Are APIs and SOA Converging?Are APIs and SOA Converging?
Are APIs and SOA Converging?Akana
 
Are APIs and SOA Converging
Are APIs and SOA ConvergingAre APIs and SOA Converging
Are APIs and SOA ConvergingSachin Agarwal
 
Write Generic Code with the Tooling API
Write Generic Code with the Tooling APIWrite Generic Code with the Tooling API
Write Generic Code with the Tooling APIAdam Olshansky
 
API and SOA: Two Sides of the Same Coin?
API and SOA: Two Sides of the Same Coin?API and SOA: Two Sides of the Same Coin?
API and SOA: Two Sides of the Same Coin?Akana
 
API and SOA: Two sides of the same coin
API and SOA: Two sides of the same coinAPI and SOA: Two sides of the same coin
API and SOA: Two sides of the same coinSachin Agarwal
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)Tom Johnson
 
APIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidadAPIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidadSoftware Guru
 
How Open Source Embiggens Salesforce.com
How Open Source Embiggens Salesforce.comHow Open Source Embiggens Salesforce.com
How Open Source Embiggens Salesforce.comSalesforce Engineering
 
Toronto node js_meetup
Toronto node js_meetupToronto node js_meetup
Toronto node js_meetupShubhra Kar
 
Building Your API for Longevity
Building Your API for LongevityBuilding Your API for Longevity
Building Your API for LongevityMuleSoft
 

Similar to API Description Languages (20)

API Description Languages: Which Is The Right One For Me?
 API Description Languages: Which Is The Right One For Me?  API Description Languages: Which Is The Right One For Me?
API Description Languages: Which Is The Right One For Me?
 
API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?API Description Languages: Which is the Right One for Me?
API Description Languages: Which is the Right One for Me?
 
Rest api design by george reese
Rest api design by george reeseRest api design by george reese
Rest api design by george reese
 
Punta Dreamin 17 Generic Apex and Tooling Api
Punta Dreamin 17 Generic Apex and Tooling ApiPunta Dreamin 17 Generic Apex and Tooling Api
Punta Dreamin 17 Generic Apex and Tooling Api
 
Building a REST API for Longevity
Building a REST API for LongevityBuilding a REST API for Longevity
Building a REST API for Longevity
 
Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)Swagger APIs for Humans and Robots (Gluecon)
Swagger APIs for Humans and Robots (Gluecon)
 
Are APIs and SOA Converging?
Are APIs and SOA Converging?Are APIs and SOA Converging?
Are APIs and SOA Converging?
 
Are APIs and SOA Converging?
Are APIs and SOA Converging?Are APIs and SOA Converging?
Are APIs and SOA Converging?
 
Are APIs and SOA Converging
Are APIs and SOA ConvergingAre APIs and SOA Converging
Are APIs and SOA Converging
 
Write Generic Code with the Tooling API
Write Generic Code with the Tooling APIWrite Generic Code with the Tooling API
Write Generic Code with the Tooling API
 
Web servicesoverview
Web servicesoverviewWeb servicesoverview
Web servicesoverview
 
API and SOA: Two Sides of the Same Coin?
API and SOA: Two Sides of the Same Coin?API and SOA: Two Sides of the Same Coin?
API and SOA: Two Sides of the Same Coin?
 
API and SOA: Two sides of the same coin
API and SOA: Two sides of the same coinAPI and SOA: Two sides of the same coin
API and SOA: Two sides of the same coin
 
Web servicesoverview
Web servicesoverviewWeb servicesoverview
Web servicesoverview
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)
 
APIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidadAPIs distribuidos con alta escalabilidad
APIs distribuidos con alta escalabilidad
 
SGCE 2015 REST APIs
SGCE 2015 REST APIsSGCE 2015 REST APIs
SGCE 2015 REST APIs
 
How Open Source Embiggens Salesforce.com
How Open Source Embiggens Salesforce.comHow Open Source Embiggens Salesforce.com
How Open Source Embiggens Salesforce.com
 
Toronto node js_meetup
Toronto node js_meetupToronto node js_meetup
Toronto node js_meetup
 
Building Your API for Longevity
Building Your API for LongevityBuilding Your API for Longevity
Building Your API for Longevity
 

More from Akana

Delivering on Personalization with the Power of APIs
Delivering on Personalization with the Power of APIsDelivering on Personalization with the Power of APIs
Delivering on Personalization with the Power of APIsAkana
 
A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...
A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...
A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...Akana
 
The Business Value for Internal APIs in the Enterprise
The Business Value for Internal APIs in the EnterpriseThe Business Value for Internal APIs in the Enterprise
The Business Value for Internal APIs in the EnterpriseAkana
 
Lifecycle Manager and the Lifecycle API
Lifecycle Manager and the Lifecycle APILifecycle Manager and the Lifecycle API
Lifecycle Manager and the Lifecycle APIAkana
 
Enterprise API Adoption Patterns
Enterprise API Adoption PatternsEnterprise API Adoption Patterns
Enterprise API Adoption PatternsAkana
 
Intermediary for Microsoft: Product Overview and Demo
Intermediary for Microsoft: Product Overview and DemoIntermediary for Microsoft: Product Overview and Demo
Intermediary for Microsoft: Product Overview and DemoAkana
 
API Security: Securing Digital Channels and Mobile Apps Against Hacks
API Security: Securing Digital Channels and Mobile Apps Against HacksAPI Security: Securing Digital Channels and Mobile Apps Against Hacks
API Security: Securing Digital Channels and Mobile Apps Against HacksAkana
 
Driving Business Partner Adoption with APIs
Driving Business Partner Adoption with APIsDriving Business Partner Adoption with APIs
Driving Business Partner Adoption with APIsAkana
 
Jumping Ahead with Enterprise APIs
Jumping Ahead with Enterprise APIsJumping Ahead with Enterprise APIs
Jumping Ahead with Enterprise APIsAkana
 
The Datacenter API
The Datacenter APIThe Datacenter API
The Datacenter APIAkana
 
Turbo Charge DataPower to Reach Your SOA Goals
Turbo Charge DataPower to Reach Your SOA Goals Turbo Charge DataPower to Reach Your SOA Goals
Turbo Charge DataPower to Reach Your SOA Goals Akana
 
The API Economy is Here: Facebook, Twitter, Netflix and Your IT Enterprise
The API Economy is Here: Facebook, Twitter, Netflix and Your IT EnterpriseThe API Economy is Here: Facebook, Twitter, Netflix and Your IT Enterprise
The API Economy is Here: Facebook, Twitter, Netflix and Your IT EnterpriseAkana
 
Using APIs
Using APIsUsing APIs
Using APIsAkana
 
Using APIs for better Business Partnerships
Using APIs for better Business PartnershipsUsing APIs for better Business Partnerships
Using APIs for better Business PartnershipsAkana
 
API Security: Does My Business Need OAuth?
API Security: Does My Business Need OAuth?API Security: Does My Business Need OAuth?
API Security: Does My Business Need OAuth?Akana
 
Best Practices: The Role of API Management
Best Practices: The Role of API ManagementBest Practices: The Role of API Management
Best Practices: The Role of API ManagementAkana
 
API Management - A Transformation
API Management - A TransformationAPI Management - A Transformation
API Management - A TransformationAkana
 
A Peek Into The Future of Mobile-Enabled Health Care
A Peek Into The Future of Mobile-Enabled Health CareA Peek Into The Future of Mobile-Enabled Health Care
A Peek Into The Future of Mobile-Enabled Health CareAkana
 
Unified Security for Mobile, APIs and the Web
Unified Security for Mobile, APIs and the WebUnified Security for Mobile, APIs and the Web
Unified Security for Mobile, APIs and the WebAkana
 
API Frenzy: The Implications and Planning for a Successful API Strategy
API Frenzy: The Implications and Planning for a Successful API StrategyAPI Frenzy: The Implications and Planning for a Successful API Strategy
API Frenzy: The Implications and Planning for a Successful API StrategyAkana
 

More from Akana (20)

Delivering on Personalization with the Power of APIs
Delivering on Personalization with the Power of APIsDelivering on Personalization with the Power of APIs
Delivering on Personalization with the Power of APIs
 
A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...
A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...
A New Breed of Technical Leaders: The 101 to Defining Your API Business Stra...
 
The Business Value for Internal APIs in the Enterprise
The Business Value for Internal APIs in the EnterpriseThe Business Value for Internal APIs in the Enterprise
The Business Value for Internal APIs in the Enterprise
 
Lifecycle Manager and the Lifecycle API
Lifecycle Manager and the Lifecycle APILifecycle Manager and the Lifecycle API
Lifecycle Manager and the Lifecycle API
 
Enterprise API Adoption Patterns
Enterprise API Adoption PatternsEnterprise API Adoption Patterns
Enterprise API Adoption Patterns
 
Intermediary for Microsoft: Product Overview and Demo
Intermediary for Microsoft: Product Overview and DemoIntermediary for Microsoft: Product Overview and Demo
Intermediary for Microsoft: Product Overview and Demo
 
API Security: Securing Digital Channels and Mobile Apps Against Hacks
API Security: Securing Digital Channels and Mobile Apps Against HacksAPI Security: Securing Digital Channels and Mobile Apps Against Hacks
API Security: Securing Digital Channels and Mobile Apps Against Hacks
 
Driving Business Partner Adoption with APIs
Driving Business Partner Adoption with APIsDriving Business Partner Adoption with APIs
Driving Business Partner Adoption with APIs
 
Jumping Ahead with Enterprise APIs
Jumping Ahead with Enterprise APIsJumping Ahead with Enterprise APIs
Jumping Ahead with Enterprise APIs
 
The Datacenter API
The Datacenter APIThe Datacenter API
The Datacenter API
 
Turbo Charge DataPower to Reach Your SOA Goals
Turbo Charge DataPower to Reach Your SOA Goals Turbo Charge DataPower to Reach Your SOA Goals
Turbo Charge DataPower to Reach Your SOA Goals
 
The API Economy is Here: Facebook, Twitter, Netflix and Your IT Enterprise
The API Economy is Here: Facebook, Twitter, Netflix and Your IT EnterpriseThe API Economy is Here: Facebook, Twitter, Netflix and Your IT Enterprise
The API Economy is Here: Facebook, Twitter, Netflix and Your IT Enterprise
 
Using APIs
Using APIsUsing APIs
Using APIs
 
Using APIs for better Business Partnerships
Using APIs for better Business PartnershipsUsing APIs for better Business Partnerships
Using APIs for better Business Partnerships
 
API Security: Does My Business Need OAuth?
API Security: Does My Business Need OAuth?API Security: Does My Business Need OAuth?
API Security: Does My Business Need OAuth?
 
Best Practices: The Role of API Management
Best Practices: The Role of API ManagementBest Practices: The Role of API Management
Best Practices: The Role of API Management
 
API Management - A Transformation
API Management - A TransformationAPI Management - A Transformation
API Management - A Transformation
 
A Peek Into The Future of Mobile-Enabled Health Care
A Peek Into The Future of Mobile-Enabled Health CareA Peek Into The Future of Mobile-Enabled Health Care
A Peek Into The Future of Mobile-Enabled Health Care
 
Unified Security for Mobile, APIs and the Web
Unified Security for Mobile, APIs and the WebUnified Security for Mobile, APIs and the Web
Unified Security for Mobile, APIs and the Web
 
API Frenzy: The Implications and Planning for a Successful API Strategy
API Frenzy: The Implications and Planning for a Successful API StrategyAPI Frenzy: The Implications and Planning for a Successful API Strategy
API Frenzy: The Implications and Planning for a Successful API Strategy
 

Recently uploaded

Dev Dives: Streamline document processing with UiPath Studio Web
Dev Dives: Streamline document processing with UiPath Studio WebDev Dives: Streamline document processing with UiPath Studio Web
Dev Dives: Streamline document processing with UiPath Studio WebUiPathCommunity
 
A Deep Dive on Passkeys: FIDO Paris Seminar.pptx
A Deep Dive on Passkeys: FIDO Paris Seminar.pptxA Deep Dive on Passkeys: FIDO Paris Seminar.pptx
A Deep Dive on Passkeys: FIDO Paris Seminar.pptxLoriGlavin3
 
The Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptx
The Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptxThe Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptx
The Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptxLoriGlavin3
 
SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024Lorenzo Miniero
 
SAP Build Work Zone - Overview L2-L3.pptx
SAP Build Work Zone - Overview L2-L3.pptxSAP Build Work Zone - Overview L2-L3.pptx
SAP Build Work Zone - Overview L2-L3.pptxNavinnSomaal
 
Unleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding ClubUnleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding ClubKalema Edgar
 
Gen AI in Business - Global Trends Report 2024.pdf
Gen AI in Business - Global Trends Report 2024.pdfGen AI in Business - Global Trends Report 2024.pdf
Gen AI in Business - Global Trends Report 2024.pdfAddepto
 
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek SchlawackFwdays
 
DevEX - reference for building teams, processes, and platforms
DevEX - reference for building teams, processes, and platformsDevEX - reference for building teams, processes, and platforms
DevEX - reference for building teams, processes, and platformsSergiu Bodiu
 
DSPy a system for AI to Write Prompts and Do Fine Tuning
DSPy a system for AI to Write Prompts and Do Fine TuningDSPy a system for AI to Write Prompts and Do Fine Tuning
DSPy a system for AI to Write Prompts and Do Fine TuningLars Bell
 
How AI, OpenAI, and ChatGPT impact business and software.
How AI, OpenAI, and ChatGPT impact business and software.How AI, OpenAI, and ChatGPT impact business and software.
How AI, OpenAI, and ChatGPT impact business and software.Curtis Poe
 
New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024BookNet Canada
 
The Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptx
The Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptxThe Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptx
The Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptxLoriGlavin3
 
Commit 2024 - Secret Management made easy
Commit 2024 - Secret Management made easyCommit 2024 - Secret Management made easy
Commit 2024 - Secret Management made easyAlfredo García Lavilla
 
WordPress Websites for Engineers: Elevate Your Brand
WordPress Websites for Engineers: Elevate Your BrandWordPress Websites for Engineers: Elevate Your Brand
WordPress Websites for Engineers: Elevate Your Brandgvaughan
 
Streamlining Python Development: A Guide to a Modern Project Setup
Streamlining Python Development: A Guide to a Modern Project SetupStreamlining Python Development: A Guide to a Modern Project Setup
Streamlining Python Development: A Guide to a Modern Project SetupFlorian Wilhelm
 
Connect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck PresentationConnect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck PresentationSlibray Presentation
 
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024BookNet Canada
 
Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 365Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 3652toLead Limited
 
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptxUse of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptxLoriGlavin3
 

Recently uploaded (20)

Dev Dives: Streamline document processing with UiPath Studio Web
Dev Dives: Streamline document processing with UiPath Studio WebDev Dives: Streamline document processing with UiPath Studio Web
Dev Dives: Streamline document processing with UiPath Studio Web
 
A Deep Dive on Passkeys: FIDO Paris Seminar.pptx
A Deep Dive on Passkeys: FIDO Paris Seminar.pptxA Deep Dive on Passkeys: FIDO Paris Seminar.pptx
A Deep Dive on Passkeys: FIDO Paris Seminar.pptx
 
The Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptx
The Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptxThe Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptx
The Role of FIDO in a Cyber Secure Netherlands: FIDO Paris Seminar.pptx
 
SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024
 
SAP Build Work Zone - Overview L2-L3.pptx
SAP Build Work Zone - Overview L2-L3.pptxSAP Build Work Zone - Overview L2-L3.pptx
SAP Build Work Zone - Overview L2-L3.pptx
 
Unleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding ClubUnleash Your Potential - Namagunga Girls Coding Club
Unleash Your Potential - Namagunga Girls Coding Club
 
Gen AI in Business - Global Trends Report 2024.pdf
Gen AI in Business - Global Trends Report 2024.pdfGen AI in Business - Global Trends Report 2024.pdf
Gen AI in Business - Global Trends Report 2024.pdf
 
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
 
DevEX - reference for building teams, processes, and platforms
DevEX - reference for building teams, processes, and platformsDevEX - reference for building teams, processes, and platforms
DevEX - reference for building teams, processes, and platforms
 
DSPy a system for AI to Write Prompts and Do Fine Tuning
DSPy a system for AI to Write Prompts and Do Fine TuningDSPy a system for AI to Write Prompts and Do Fine Tuning
DSPy a system for AI to Write Prompts and Do Fine Tuning
 
How AI, OpenAI, and ChatGPT impact business and software.
How AI, OpenAI, and ChatGPT impact business and software.How AI, OpenAI, and ChatGPT impact business and software.
How AI, OpenAI, and ChatGPT impact business and software.
 
New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
 
The Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptx
The Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptxThe Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptx
The Fit for Passkeys for Employee and Consumer Sign-ins: FIDO Paris Seminar.pptx
 
Commit 2024 - Secret Management made easy
Commit 2024 - Secret Management made easyCommit 2024 - Secret Management made easy
Commit 2024 - Secret Management made easy
 
WordPress Websites for Engineers: Elevate Your Brand
WordPress Websites for Engineers: Elevate Your BrandWordPress Websites for Engineers: Elevate Your Brand
WordPress Websites for Engineers: Elevate Your Brand
 
Streamlining Python Development: A Guide to a Modern Project Setup
Streamlining Python Development: A Guide to a Modern Project SetupStreamlining Python Development: A Guide to a Modern Project Setup
Streamlining Python Development: A Guide to a Modern Project Setup
 
Connect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck PresentationConnect Wave/ connectwave Pitch Deck Presentation
Connect Wave/ connectwave Pitch Deck Presentation
 
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
 
Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 365Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 365
 
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptxUse of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
 

API Description Languages

  • 1. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. API Description Languages! Laura Heritage! Director of API Strategy!
  • 2. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. What is an API Description Language (API DL)?! Contract Human DocsMetadataBlueprint
  • 3. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 4. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 5. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. Many API DL Are Available Today! Hypermedia
  • 6. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 7. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. How Do You Choose?!
  • 8. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. Define 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
  • 9. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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 -
  • 10. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 11. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 12. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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.
  • 13. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. RAML! Start with tutorial at RAML.org
  • 14. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 15. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. Document Generation! •  RAML to HTML •  RAML to HTML - PHP
  • 16. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 17. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. SWAGGER! Swagger Community •  https://github.com/wordnik/swagger-spec Swagger Getting Started •  https://github.com/wordnik/swagger-spec/wiki
  • 18. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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.
  • 19. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 20. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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.
  • 21. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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.
  • 22. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 23. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. 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
  • 24. Copyright © 2001-2013 SOA Software, Inc. All Rights Reserved. References! •  Another API-Blueprint, RAML, Swagger Comparison – Ole Lensmar •  Investigating API Developer Tooling - @DanMayer
  • 25. Copyright © 2001-2014 SOA Software, Inc. All Rights Reserved. Questions!