Slides from http://apistrategyconference.com/ on swagger in your REST api

1. Swagger for your REST API
Tony Tam

2. REST as the “new” API
Revisiting the JAR
• Expose & share low-level functionality
• Reduced plumbing, focus on business logic
• Helped us build big, monolithic apps
• Dependency hell

3. REST as the “new” API
• Complex building blocks for your application
• Authentication
• Photo storage
• Analytics
• Language & deployment independent
• Vertical scaling addressed by smaller,
decoupled services

4. Integrating 3 rd Party APIs
How about
Documentation?"

5. Integrating 3 rd Party APIs
IDE
Javadocs?" support?"
How about
Documentation?"
Stack
Overflow?" JSDoc?"

6. Integrating 3 rd Party APIs

7. Integrating 3 rd Party APIs

8. Integrating 3 rd Party APIs

9. Integrating 3 rd Party APIs

10. So… How do we describe APIs?
Javadocs?" WADL"
WADL2?"
Developer WSDL?"
Docs?"

11. The Swagger Specification
It’s a spec!
• JSON
• Coupled of decoupled
• Machine-readable
• Language agnostic
• Distributed by Design
An Interface
for your API

12. Benefits of an Interface
It’s done in JSON
Existing
• Generate manually
API?
• Deploy statically
• Generate automatically by server integration
• 9 languages, 16+ frameworks

13. Benefits of an Interface
Machine-readable Your boss
can try your
API

14. Benefits of an Interface
Distributed design
API Declaration"
/pet" Server 1"
/store"
Server 2"
Resource"
Listing"
/user"
Swagger Spec Server"
Server 3"

15. How does this help you?
Server"
Developer"
Client-Side
Developer"

16. How does this help you?
Server"
Developer"
OMG I can
code w/o
waiting for The client
back end!" developer
isn’t bugging
me!"
Client-Side
Developer"

17. How about your clients?
REST or SDK?
• Please! Strive to
remove your logic
from clients
/api/pet.json/1?delete (GET)
/api/pet.json/1 (DELETE)
/api/pet.json/1 (POST empty)

18. How about your clients?
REST or SDK?
• Please! Strive to
remove your logic
from clients
/api/pet.json/1?delete (GET)
/api/pet.json/1 (DELETE)
/api/pet.json/1 (POST empty)
These all (This is your
“work”
job, not your
clients’)

19. How about your clients?
Swagger can help (if you like)
• Machine-readable => code generator
• Uses non-ghetto {{mustache}} templates
• Make client libraries “your way”

20. How about your API service?
Swagger can again help (if you like)
• Code-generator, not “client generator”
• Build your server from the interface

21. Interfaces are nice
• Developers know what they’re building
• Clients know what they’re getting
• Machines and humans can interpret them
• Teams can develop in parallel

22. Swagger is FOSS

23. Where to go next
More info + demo
http://developers.helloreverb.com/swagger/
Swagger specification
https://github.com/wordnik/swagger-core/wiki @fehguy"
JVM server implementation
https://github.com/wordnik/swagger-core
Node.js server implementation
https://github.com/wordnik/swagger-core
swagger-ui
https://github.com/wordnik/swagger-ui
swagger-codegen
https://github.com/wordnik/swagger-codegen