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?"
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
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