Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.
API Languages
& Contract-First Design
John Zaccone - Software Engineer
http://www.ipponusa.com
Overview
● API Documentation Languages
● Demo
● Contract-First Design
● Refactor the Demo
● Cool Tools
2
Let’s REST together
3
We need Documentation for our REST APIs
● API Doc Languages define a specification
● Specifications are Machine-Readable
●...
Value Added
● API Doc specifications are open-source
● Value comes from suite of tools and parsers
build on that specifica...
Bottom Up or Top Down
● Top-down (aka contract-first)
○ Write doc first
○ Generate code from docs
● Bottom-up
○ Write code...
Comparing What’s Out There
Swagger RAML API Blueprint
Sponsored By Reverb Mulesoft Apiary
Initial Commit July, 2011 Sep, 2...
Modeling REST
They all support:
● Resources
● HTTP Methods
● Query Parameters
● URL Parameters
● Header Parameters
● Statu...
Modeling REST
Swagger RAML API Blueprint
Authentication Basic, API-Key,
OAuth2
Basic, Digest,
OAuth1, OAuth2
Basic, API-Ke...
Integrations ⭑
Swagger RAML APIBlueprint
Server-Side java, scala, ruby,
nodejs
java
Client-Side scala, flash, java,
objc, ...
Overview
● API Documentation Languages
● Demo
● Contract-First Design
● Refactor the Demo
● Cool Tools
11
Pet Store API
● Get all Pets
● Add a Pet
● Get Pet by ID
● Paging and Security
12
A History
● Swagger starts in July 2011, provides API
documentation automatically from code
● Push for “contract-first” de...
Overview
● API Documentation Languages
● Demo
● Contract-First Design
● Refactor the Demo
● Cool Tools
14
Contracts Are Valuable
● Enable 3rd-party developers to build
awesome apps
● Channel of revenue
● Drive innovation by shar...
16
Problems
● Doesn’t consider needs of consumers
● Not-so-nice APIs
○ Complicated models
○ Unfriendly business logic
● Consu...
18
API Facade Pattern
● Hide the complexity
● Define an API that users want to use
● Simple models
● Consistent interfaces
19
Agile in API Design
20
Contract-First
Swagger RAML API Blueprint
Language
Writability
Good Good Good
Re-usable
Patterns
Good Great OK
Mock Server...
Common Patterns in REST
● Many patterns of REST are repeated over
and over...
● Get /my_collection
● Post /my_collection
●...
Patterns with RAML
● ResourceTypes define common behaviors
for resources
● Traits define common behaviors for
methods
● Ex...
Overview
● API Documentation Languages
● Demo
● Contract-First Design
● Refactor the Demo
● Cool Tools
24
Take Away
● Swagger wins
○ Community support
○ Extensive client-side and server-side integrations
● RAML wins
○ Advanced r...
Keep an Eye Out...
● Community growth in RAML
● Better ways to write APIs in Swagger
● @swagger, @mulesoft
● swagger2raml,...
Overview
● API Documentation Languages
● Demo
● Contract-First Design
● Refactor the Demo
● Cool Tools
27
Client SDK Generator
● https://github.com/swagger-
api/swagger-codegen
● Supports a growing list of languages
28
RAML API Designer with MongoDB
● https://github.com/brianmc/raml-store
29
Enterprise Solutions
● RAML (https://anypoint.mulesoft.com)
● API Blueprint (http://apiary.io/)
30
Verify Code == Docs
● Aboa: (https://github.com/cybertk/abao)
● Dredd: (https://github.com/apiaryio/dredd)
● Command-line ...
API Mashups
● API Notebook (https://api-notebook.anypoint.
mulesoft.com)
● Live javascript
● Quickly create clients from R...
Other
● RAML and Swagger imports into your
Postman client
● Sublime plugin for API Blueprint and
RAML
● raml2html (https:/...
Questions
?jzaccone@ipponusa.com
@JohnZaccone
34
References
● https://speakerdeck.com/apistrat/another-api-blueprint-raml-and-swagger-comparison
● https://blog.soa.com/spr...
Prochain SlideShare
Chargement dans…5
×

API Documentation Languages and Contract First Design

1 531 vues

Publié le

Learn about API documentation languages and why you should use these languages to document your REST APIs. We’ll take a comparative look of the top open-source documentation languages, and dive deeper into one of the languages in a hands-on demonstration. Also, learn how to incorporate an API documentation language into your team’s process, specifically using contract-first design, and learn about the tooling that will make your life easier.

Publié dans : Ingénierie
  • Soyez le premier à commenter

API Documentation Languages and Contract First Design

  1. 1. API Languages & Contract-First Design John Zaccone - Software Engineer http://www.ipponusa.com
  2. 2. Overview ● API Documentation Languages ● Demo ● Contract-First Design ● Refactor the Demo ● Cool Tools 2
  3. 3. Let’s REST together 3
  4. 4. We need Documentation for our REST APIs ● API Doc Languages define a specification ● Specifications are Machine-Readable ● Parsers and tools that understand the specification can provide great features for little work 4
  5. 5. Value Added ● API Doc specifications are open-source ● Value comes from suite of tools and parsers build on that specification ● Interactive documentation, code generation, postman collections, mock servers, traffic inspection, API testing and analytics and much, much more 5
  6. 6. Bottom Up or Top Down ● Top-down (aka contract-first) ○ Write doc first ○ Generate code from docs ● Bottom-up ○ Write code first ○ Generate docs from code 6
  7. 7. Comparing What’s Out There Swagger RAML API Blueprint Sponsored By Reverb Mulesoft Apiary Initial Commit July, 2011 Sep, 2013 April, 2013 Designed For Code First Contract First Contract First Workgroup Yes Yes No Format JSON w/ YAML YAML Markdown Community 2,386 942 1,614 7
  8. 8. Modeling REST They all support: ● Resources ● HTTP Methods ● Query Parameters ● URL Parameters ● Header Parameters ● Status Codes, Content-Types 8
  9. 9. Modeling REST Swagger RAML API Blueprint Authentication Basic, API-Key, OAuth2 Basic, Digest, OAuth1, OAuth2 Basic, API-Key, OAuth2 File Inclusions Yes, $ref Yes Nested Resources Yes Yes API Versioning Yes Yes Sample Representations Yes Yes 9
  10. 10. Integrations ⭑ Swagger RAML APIBlueprint Server-Side java, scala, ruby, nodejs java Client-Side scala, flash, java, objc, php, python, ruby js Parsers js, java js, java c++, .net, ruby 10
  11. 11. Overview ● API Documentation Languages ● Demo ● Contract-First Design ● Refactor the Demo ● Cool Tools 11
  12. 12. Pet Store API ● Get all Pets ● Add a Pet ● Get Pet by ID ● Paging and Security 12
  13. 13. A History ● Swagger starts in July 2011, provides API documentation automatically from code ● Push for “contract-first” design ● RAML (Sept, 2013) found that Swagger “was best suited for documenting an existing API, not for designing an API from scratch” ● Swagger 2.0 addresses contract-first design weaknesses (~Sept, 2014) 13
  14. 14. Overview ● API Documentation Languages ● Demo ● Contract-First Design ● Refactor the Demo ● Cool Tools 14
  15. 15. Contracts Are Valuable ● Enable 3rd-party developers to build awesome apps ● Channel of revenue ● Drive innovation by sharing internal APIs ● APIs are enablers 15
  16. 16. 16
  17. 17. Problems ● Doesn’t consider needs of consumers ● Not-so-nice APIs ○ Complicated models ○ Unfriendly business logic ● Consumers might have a different view of the world 17
  18. 18. 18
  19. 19. API Facade Pattern ● Hide the complexity ● Define an API that users want to use ● Simple models ● Consistent interfaces 19
  20. 20. Agile in API Design 20
  21. 21. Contract-First Swagger RAML API Blueprint Language Writability Good Good Good Re-usable Patterns Good Great OK Mock Server 3rd Party Yes Yes, External Tool Collaboration Platform Open-Source Solution? Enterprise Offering Enterprise Offering 21
  22. 22. Common Patterns in REST ● Many patterns of REST are repeated over and over... ● Get /my_collection ● Post /my_collection ● Filtering, ordering and paging 22
  23. 23. Patterns with RAML ● ResourceTypes define common behaviors for resources ● Traits define common behaviors for methods ● Example: /pets type: collection 23
  24. 24. Overview ● API Documentation Languages ● Demo ● Contract-First Design ● Refactor the Demo ● Cool Tools 24
  25. 25. Take Away ● Swagger wins ○ Community support ○ Extensive client-side and server-side integrations ● RAML wins ○ Advanced re-use patterns for resources and methods ○ Supports multiple files, and enterprise solution for collaboration ○ Great for designing APIs from scratch 25
  26. 26. Keep an Eye Out... ● Community growth in RAML ● Better ways to write APIs in Swagger ● @swagger, @mulesoft ● swagger2raml, raml2swagger 26
  27. 27. Overview ● API Documentation Languages ● Demo ● Contract-First Design ● Refactor the Demo ● Cool Tools 27
  28. 28. Client SDK Generator ● https://github.com/swagger- api/swagger-codegen ● Supports a growing list of languages 28
  29. 29. RAML API Designer with MongoDB ● https://github.com/brianmc/raml-store 29
  30. 30. Enterprise Solutions ● RAML (https://anypoint.mulesoft.com) ● API Blueprint (http://apiary.io/) 30
  31. 31. Verify Code == Docs ● Aboa: (https://github.com/cybertk/abao) ● Dredd: (https://github.com/apiaryio/dredd) ● Command-line tool to check if service implementation matches RAML doc ● Integrate into your CI (Jenkins) Build 31
  32. 32. API Mashups ● API Notebook (https://api-notebook.anypoint. mulesoft.com) ● Live javascript ● Quickly create clients from RAML definitions ● Make PoC and prototypes ● Saved as Github Gists 32
  33. 33. Other ● RAML and Swagger imports into your Postman client ● Sublime plugin for API Blueprint and RAML ● raml2html (https://github. com/kevinrenskers/raml2html) 33
  34. 34. Questions ?jzaccone@ipponusa.com @JohnZaccone 34
  35. 35. References ● https://speakerdeck.com/apistrat/another-api-blueprint-raml-and-swagger-comparison ● https://blog.soa.com/spread-the-wealth-developer-communities-for-your-apis-part-2-top- down-or-bottom-up-structuring-your-community/ ● https://www.youtube.com/watch?v=vu8_QLkW1mg ● http://apiux.com/2013/04/09/rest-metadata-formats/ ● http://stackoverflow.com/questions/26917188/how-to-break-swagger-2-0-json-file-into- multiple-modules/26917653#26917653 ● http://raml.org/spec.html ● http://stackoverflow.com/users/1103327/ron?tab=answers&sort=votes (Swagger Questions) ● http://www.programmableweb.com/news/reverb-apigee-announce-swagger-2.0- workgroup/2014/05/23 ● http://forums.raml.org/t/how-is-this-different-from-swagger/24 ● https://github.com/swagger-api/swagger-spec/wiki/Swagger-1.2-to-2.0-Migration-Guide 35

×