Swagger APIs for Humans and Robots (Gluecon)
Upcoming SlideShare
Loading in...5
×
 

Like this? Share it with your network

Share

Swagger APIs for Humans and Robots (Gluecon)

on

  • 2,919 views

Presentation to Gluecon 2014 about Swagger for API development and adoption of services. Reverb also announced the Swagger 2.0 Working Group, with Apigee as a founding member

Presentation to Gluecon 2014 about Swagger for API development and adoption of services. Reverb also announced the Swagger 2.0 Working Group, with Apigee as a founding member

Statistics

Views

Total Views
2,919
Views on SlideShare
2,018
Embed Views
901

Actions

Likes
2
Downloads
19
Comments
0

10 Embeds 901

http://www.scoop.it 601
http://www.3scale.net 213
https://twitter.com 65
http://www.slideee.com 11
http://feedly.com 6
http://threescale.staging.wpengine.com 1
http://news.google.com 1
http://www.google.co.in 1
http://plus.url.google.com 1
http://translate.googleusercontent.com 1
More...

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • Services, internal or external, are the new unit of software
  • How modules are documented varies wildly by language, technology

Swagger APIs for Humans and Robots (Gluecon) Presentation Transcript

  • 1. Swagger APIs for Humans (and Robots) @fehguy
  • 2. Swagger Philosophy
  • 3. Swagger Philosophy Service documentation sucks typically
  • 4. Swagger Philosophy • Communicating is too much work – Users don’t want to write YOUR SDK – If you’re good at Ruby, you suck at GO • Consumers need a contract – Service logic doesn’t belong in the SDK • Services are plumbing – We shouldn’t all be plumbers – Business logic is your business
  • 5. Swagger Philosophy • Solved by machine-readable, discoverable API contract • Should speed up, not slow down development process • External services/proxies not required
  • 6. What is Swagger? • An interface to your service – Described in JSON • It is a contract to your service • Enables “bigotry-free” restful design with emphasis on getting things done – Many ways to delete a Pet
  • 7. How does it work? • Discoverable at runtime, not compile-time • It’s just JSON • No server integration required – You can describe an API that’s not even yours – Deploy anywhere! Put it on github! – Swagger is JUST a way to describe an API
  • 8. But Why? • Machine-readable contract – Description of *everything* the server can do – Server-controlled documentation – Server/language/platform/deployment agnostic • Documentation, code generation, client generation – Like Headers for C, Interfaces for Java
  • 9. Swagger UI
  • 10. Client SDKs • Your consumers want to use your service – How they want – Not write your software
  • 11. How do you add Swagger? • Static Files – Manually crafted JSON • Heuristics – Traffic inspection • Code inspection – Code comments, static annotations • Runtime generation It’s just JSON!
  • 12. Client Generation https://github.com/wordnik/swagger-codegen • Templates can be generated your way • Typed and untyped languages Groovy Java Android async-scala C# Flash Objective C PHP Python Python 3 Ruby Scala
  • 13. Client Generation • Requires a proper API definition • Type info, parameters, input/output models • Protocol, path, authentication • Templates are a starting point – Clone, configure, put in workflow
  • 14. Client Generation • Configuration Script – Packages – Imports – Type Mapping – Packaging info • Group ID, Artifact ID, version • Templates – Boilerplate code
  • 15. Client Generation • Codegen for client generation
  • 16. Static Doc Generation • Codegen !== client generation • Templates are generic
  • 17. Static Doc Generation
  • 18. Server Generation • Specs can generate servers
  • 19. How do you write Software? • Code first? • Design first? • Hybrid? One size does NOT fit all
  • 20. Top Down vs. Bottom-up • Design-first is not this (anymore)
  • 21. Top Down • GUI vs. XML? The world chose GUI! • GUI vs. JSON? • GUI vs. YAML?
  • 22. Top Down? XML: 453 Lines JSON: 512 Lines YAML: 400 Lines It’s not about the line count!
  • 23. Introducing Swagger Editor!
  • 24. Evolution of Swagger • Swagger Editor – Angular, Ace – OSS, Apache 2.0 • Thank you Community! – 500k downloads of java framework alone – ~10k production deployments – 4k stars, 1600 forks – Big & Small
  • 25. Swagger 2.0 Working Group • Give your input on Swagger 2.0 Specification • Coming this Summer • More info: – http://swagger.wordnik.com • Join the evolution – https://github.com/wordnik/swagger-spec
  • 26. Swagger has a Community • Server integrations JAX-RS (java) Scalatra (scala) Spring MVC (java) Spray (scala) Composer (PHP) django (python) Flask (python) Go Maven (JAX-RS) ServiceStack (.net) Doctrine (PHP) Express (JS) Restler (PHP) Hapi (JS) Clojure
  • 27. Swagger is FOSS • Apache 2 License https://github.com/wordnik/swagger-spec https://github.com/wordnik/swagger-core https://github.com/wordnik/swagger-codegen https://github.com/wordnik/swagger-editor https://github.com/wordnik/swagger-ui https://github.com/wordnik/swagger-node-express https://github.com/scalatra/scalatra
  • 28. Where to go for help Google Groups • https://groups.google.com/forum/#!forum/s wagger-swaggersocket IRC • irc.freenode.net Email • apiteam@wordnik.com