SlideShare ist ein Scribd-Unternehmen logo
1 von 25
Downloaden Sie, um offline zu lesen
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!

Weitere ähnliche Inhalte

Was ist angesagt?

Microservices with Java, Spring Boot and Spring Cloud
Microservices with Java, Spring Boot and Spring CloudMicroservices with Java, Spring Boot and Spring Cloud
Microservices with Java, Spring Boot and Spring CloudEberhard Wolff
 
Spring Boot Observability
Spring Boot ObservabilitySpring Boot Observability
Spring Boot ObservabilityVMware Tanzu
 
Monetization: Unlock More Value from Your APIs
Monetization: Unlock More Value from Your APIs Monetization: Unlock More Value from Your APIs
Monetization: Unlock More Value from Your APIs Apigee | Google Cloud
 
Snyk Intro - Developer Security Essentials 2022
Snyk Intro - Developer Security Essentials 2022Snyk Intro - Developer Security Essentials 2022
Snyk Intro - Developer Security Essentials 2022Liran Tal
 
Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...
Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...
Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...Edureka!
 
REST API and CRUD
REST API and CRUDREST API and CRUD
REST API and CRUDPrem Sanil
 
I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop
I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop
I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop Apigee | Google Cloud
 
API Management Within a Microservices Architecture
API Management Within a Microservices Architecture API Management Within a Microservices Architecture
API Management Within a Microservices Architecture Nadeesha Gamage
 
Introduction to Swagger
Introduction to SwaggerIntroduction to Swagger
Introduction to SwaggerKnoldus Inc.
 
Micro-services architecture
Micro-services architectureMicro-services architecture
Micro-services architectureFarwa Ansari
 
API Gateway How-To: The Many Ways to Apply the Gateway Pattern
API Gateway How-To: The Many Ways to Apply the Gateway PatternAPI Gateway How-To: The Many Ways to Apply the Gateway Pattern
API Gateway How-To: The Many Ways to Apply the Gateway PatternVMware Tanzu
 
Building secure applications with keycloak
Building secure applications with keycloak Building secure applications with keycloak
Building secure applications with keycloak Abhishek Koserwal
 
DevSecOps: Taking a DevOps Approach to Security
DevSecOps: Taking a DevOps Approach to SecurityDevSecOps: Taking a DevOps Approach to Security
DevSecOps: Taking a DevOps Approach to SecurityAlert Logic
 
The never-ending REST API design debate
The never-ending REST API design debateThe never-ending REST API design debate
The never-ending REST API design debateRestlet
 
Slide DevSecOps Microservices
Slide DevSecOps Microservices Slide DevSecOps Microservices
Slide DevSecOps Microservices Hendri Karisma
 
B4USolution_API-Testing
B4USolution_API-TestingB4USolution_API-Testing
B4USolution_API-Testingb4usolution .
 
Practical DevSecOps Course - Part 1
Practical DevSecOps Course - Part 1Practical DevSecOps Course - Part 1
Practical DevSecOps Course - Part 1Mohammed A. Imran
 
Black and Blue APIs: Attacker's and Defender's View of API Vulnerabilities
Black and Blue APIs: Attacker's and Defender's View of API VulnerabilitiesBlack and Blue APIs: Attacker's and Defender's View of API Vulnerabilities
Black and Blue APIs: Attacker's and Defender's View of API VulnerabilitiesMatt Tesauro
 

Was ist angesagt? (20)

Microservices with Java, Spring Boot and Spring Cloud
Microservices with Java, Spring Boot and Spring CloudMicroservices with Java, Spring Boot and Spring Cloud
Microservices with Java, Spring Boot and Spring Cloud
 
Spring Boot Observability
Spring Boot ObservabilitySpring Boot Observability
Spring Boot Observability
 
Monetization: Unlock More Value from Your APIs
Monetization: Unlock More Value from Your APIs Monetization: Unlock More Value from Your APIs
Monetization: Unlock More Value from Your APIs
 
Snyk Intro - Developer Security Essentials 2022
Snyk Intro - Developer Security Essentials 2022Snyk Intro - Developer Security Essentials 2022
Snyk Intro - Developer Security Essentials 2022
 
Apigee Demo: API Platform Overview
Apigee Demo: API Platform OverviewApigee Demo: API Platform Overview
Apigee Demo: API Platform Overview
 
Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...
Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...
Git Tutorial | Git Basics - Branching, Merging, Rebasing | Learn Git | DevOps...
 
REST API and CRUD
REST API and CRUDREST API and CRUD
REST API and CRUD
 
I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop
I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop
I Love APIs 2015: Advanced Crash Course in Apigee Edge Workshop
 
API Management Within a Microservices Architecture
API Management Within a Microservices Architecture API Management Within a Microservices Architecture
API Management Within a Microservices Architecture
 
Introduction to Swagger
Introduction to SwaggerIntroduction to Swagger
Introduction to Swagger
 
DevSecOps Jenkins Pipeline -Security
DevSecOps Jenkins Pipeline -SecurityDevSecOps Jenkins Pipeline -Security
DevSecOps Jenkins Pipeline -Security
 
Micro-services architecture
Micro-services architectureMicro-services architecture
Micro-services architecture
 
API Gateway How-To: The Many Ways to Apply the Gateway Pattern
API Gateway How-To: The Many Ways to Apply the Gateway PatternAPI Gateway How-To: The Many Ways to Apply the Gateway Pattern
API Gateway How-To: The Many Ways to Apply the Gateway Pattern
 
Building secure applications with keycloak
Building secure applications with keycloak Building secure applications with keycloak
Building secure applications with keycloak
 
DevSecOps: Taking a DevOps Approach to Security
DevSecOps: Taking a DevOps Approach to SecurityDevSecOps: Taking a DevOps Approach to Security
DevSecOps: Taking a DevOps Approach to Security
 
The never-ending REST API design debate
The never-ending REST API design debateThe never-ending REST API design debate
The never-ending REST API design debate
 
Slide DevSecOps Microservices
Slide DevSecOps Microservices Slide DevSecOps Microservices
Slide DevSecOps Microservices
 
B4USolution_API-Testing
B4USolution_API-TestingB4USolution_API-Testing
B4USolution_API-Testing
 
Practical DevSecOps Course - Part 1
Practical DevSecOps Course - Part 1Practical DevSecOps Course - Part 1
Practical DevSecOps Course - Part 1
 
Black and Blue APIs: Attacker's and Defender's View of API Vulnerabilities
Black and Blue APIs: Attacker's and Defender's View of API VulnerabilitiesBlack and Blue APIs: Attacker's and Defender's View of API Vulnerabilities
Black and Blue APIs: Attacker's and Defender's View of API Vulnerabilities
 

Andere mochten auch

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
 

Andere mochten auch (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
 
API Governance
API Governance API Governance
API Governance
 
オープンイノベーション事例 アップル
オープンイノベーション事例 アップルオープンイノベーション事例 アップル
オープンイノベーション事例 アップル
 

Ähnlich wie 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
 

Ähnlich wie 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
 

Mehr von 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
 

Mehr von 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
 

Kürzlich hochgeladen

OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureEric D. Schabell
 
Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024SkyPlanner
 
Governance in SharePoint Premium:What's in the box?
Governance in SharePoint Premium:What's in the box?Governance in SharePoint Premium:What's in the box?
Governance in SharePoint Premium:What's in the box?Juan Carlos Gonzalez
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?IES VE
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemAsko Soukka
 
99.99% of Your Traces Are (Probably) Trash (SRECon NA 2024).pdf
99.99% of Your Traces  Are (Probably) Trash (SRECon NA 2024).pdf99.99% of Your Traces  Are (Probably) Trash (SRECon NA 2024).pdf
99.99% of Your Traces Are (Probably) Trash (SRECon NA 2024).pdfPaige Cruz
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfDianaGray10
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1DianaGray10
 
UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8DianaGray10
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1DianaGray10
 
UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"
UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"
UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"DianaGray10
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfJamie (Taka) Wang
 
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCostKubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCostMatt Ray
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Will Schroeder
 
Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)Commit University
 
UiPath Studio Web workshop series - Day 5
UiPath Studio Web workshop series - Day 5UiPath Studio Web workshop series - Day 5
UiPath Studio Web workshop series - Day 5DianaGray10
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPathCommunity
 
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...UbiTrack UK
 

Kürzlich hochgeladen (20)

OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability Adventure
 
Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024
 
Governance in SharePoint Premium:What's in the box?
Governance in SharePoint Premium:What's in the box?Governance in SharePoint Premium:What's in the box?
Governance in SharePoint Premium:What's in the box?
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystem
 
20230104 - machine vision
20230104 - machine vision20230104 - machine vision
20230104 - machine vision
 
99.99% of Your Traces Are (Probably) Trash (SRECon NA 2024).pdf
99.99% of Your Traces  Are (Probably) Trash (SRECon NA 2024).pdf99.99% of Your Traces  Are (Probably) Trash (SRECon NA 2024).pdf
99.99% of Your Traces Are (Probably) Trash (SRECon NA 2024).pdf
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
 
UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1
 
UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"
UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"
UiPath Clipboard AI: "A TIME Magazine Best Invention of 2023 Unveiled"
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
 
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCostKubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
KubeConEU24-Monitoring Kubernetes and Cloud Spend with OpenCost
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
 
Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)Crea il tuo assistente AI con lo Stregatto (open source python framework)
Crea il tuo assistente AI con lo Stregatto (open source python framework)
 
UiPath Studio Web workshop series - Day 5
UiPath Studio Web workshop series - Day 5UiPath Studio Web workshop series - Day 5
UiPath Studio Web workshop series - Day 5
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation Developers
 
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
 

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!