Ways you can scale your software and organization with Wordnik's Swagger framework

1. Scaling with Swagger
Tony Tam
@fehguy

2. Scaling is the Developer's Job
Was:
• Write code, make it work
• If it get slow, buy:
• Bigger server
• Bigger database
• "Enterprise" software support

3. Needs Harmony Between
• Software
• Data Tier
• Development Infrastructure
• Deployment Infrastructure
• Team
• Ability to manage it all

4. Needs Harmony Between
• Software
• Data Tier
• Development Infrastructure
• Deployment Infrastructure
• Team
• Ability to manage it Best Achieved
all
with Good
Architecture

5. Background
Biz
Tier
Data
Tier
DBA
"Bee
n

6. Common Mistakes…
• "Let's organize by horizontal!"
• "Back end shouldn't care what front end
does!"
• "Just get it launched and we'll scale with
hardware"
• "You can scale transparently with
technology X"
• "Get an Oracle consultant to speed things
up"

7. Common Problems
• Overly complicated interfaces
• Abstracted too many times
• "We can switch out entities with a simple
configuration!"
• Over-abstracted
• "We might need to change database vendors so
abstract the SQL layer"
• Over designed
• "We don't know how the client will call, so support
all possible calls!"

8. Solutions
• Many Possible
• Some suck, some good
• Let's look at Wordnik

9. Directionally Speaking
• Go Vertical!
• Ability to understand full lifecycle
• APIs as the communication of choice
• General convergence on developers
• Databases (MongoDB, Cassandra, Dynamo)
• API frameworks
• IT & QA are disappearing
• Wordnik currently has *none*
• Team, infrastructure, discipline *win*

10. Directionally Speaking
• Go Vertical!
• Ability to understand full lifecycle
• APIs as the communication of choice
• General convergence on developers
Still Room
• Databases (MongoDB, Cassandra, Dynamo)
to specialize
• API frameworks
• IT & QA are disappearing
• Wordnik currently has *none*
• Team, infrastructure, discipline *win*

11. Vertical, Explained
• Big application => micro services
Monolithic
application
"Isn't this
just
SOA?"

12. Not SOA
• This is different
• No proprietary message bus
• Decoupled objects
• Dedicated storage***
• Speak REST
• Develop your services in…
• Java
• Scala
• Ruby
• Php

13. Speak REST?
• Sounds good but…
• REST semantics vary wildly
• HATEOAS vs. practical REST?
/api/pet.json/1?delete (GET)
/api/pet.json/1 (DELETE) All
/api/pet.json/1 (POST empty) valid!
So…

14. Speak REST?
• Sounds good but…
• REST semantics vary wildly
• HATEOAS vs. practical REST?
/api/pet.json/1?delete (GET)
Peer All
/api/pet.json/1 (DELETE)
Review! valid!
/api/pet.json/1 (POST empty)
Better
Docs!
So…
API
API Styleguide
Council! !

15. Hello, Swagger
• Swagger is…
• Spec for declaring an API schema
• A framework for auto-generating the spec
• A library for client library generation
• A JSON-based test framework

16. What is this Resource Declaration?
• Listing of all available APIs
http://petstore.swagger.wordnik.com/api/resources.json
“It’s like a
sitemap for
your API!”

17. What is this Resource Declaration?
• “But I don’t want it all exposed!”
• Swagger can filter APIs by permissions
Header,
Api key, URL,
Cookies, Method
OAuth

18. What is this Resource Declaration?
• Each api is documented
http://petstore.swagger.wordnik.com/api/pet.json

19. API Documentation Highlights
• Describes
• Operations
• Models
• Permission-based filtering
• JSON and XML supported

20. Anatomy of API Documentation

21. Anatomy of API Documentation
Based on
JSON
Schema
(Draft)
http://tools.ietf.org/html/draft-zyp-json-schema-03

22. API Parameters

23. API Parameters
• Filtering on parameters
• Enumerated options w/optional default

24. API Parameters

25. How does this help?
• Generate client libs
• Invoke methods not URLs
• Pass arguments, not query params
• Don't care about how service is developed
• Different versions of java?
• Different REST frameworks?

26. How does this help?
• Generate client libs
• Invoke methods not URLs
• Pass arguments, not query params
• Don'tRESTler? how service is developed
care about JAX-RS
• Different versions of java?
• Different REST frameworks?
Client
Play! Scalatra
doesn't
care

27. Example Codegen
./bin/generate-scala-lib.sh
http://petstore.swagger.wordnik.com/api
""
"com.wordnik"
client

28. Example Invocation
Scala
Ruby

29. But What about Speed?
• Yes! REST over HTTP is slow
• Connection overhead
• Marshaling & Unmarshaling overhead
• Chatter
• JSON/XML need to diet
• It's also…
• Synchronous
• GET/POST/PUT/DELETE don't cut it

30. But What about Speed?
• Yes! REST over HTTP is slow
• Connection overhead
• Your
Marshaling & Unmarshaling overhead prod
• Chatter Database
• JSON/XML need to diet isn't doing
• It's also… REST
• Synchronous
• GET/POST/PUT/DELETE don't cut it

31. Websockets to the Rescue!
• It's…
• Full Duplex
• Persistent connections
• Completely Async
• But…
• Very finicky
• Wildly inconsistent server support
• Still in draft

32. Websockets to the Rescue!
• It's…
• Full Duplex
• Persistent connections
• Completely Async
• But…
• Very finicky
• Wildly inconsistent server support
• Still in draft

33. Abstracted by Atmosphere
https://github.com/Atmosphere/atmosphere
• Fully Sponsored by Wordnik
• Abstracts the mess
• Support on many containers
• Client fallback/draft protocol support

34. Abstracted by Atmosphere
https://github.com/Atmosphere/atmosphere
• Fully Sponsored by Wordnik
• Abstracts the mess
• Support on many containers
• Client fallback/draft protocolTomcat
support
Weblogi
Jetty c
JBoss Resin
Netty Glassfis
h

35. Swagger + Websockets
• Swagger sockets
• Same discovery interface
• Same client interface
• Same codegen
• But…
• Multiplexed connections
• Support for binary protocol
• Full Async
• Adding "subscribe" to GET/POST/PUT/DELETE

36. Swagger Sockets
• Live now on smartmoney.com
• Fully OSS
• Wire-protocol speed
• Format-agnostic
• JSON
• Binary

37. Summary
• Smaller, dedicated units of work
• Micro services => micro teams
• Full service knowledge
• Swagger is the Fabric for your Services
• Swagger sockets are like Fiber for your
grid's connectivity

38. See More…
• http://swagger.wordnik.com/
• https://github.com/wordnik/swagger-core
• https://github.com/wordnik/swagger-ui
• https://github.com/wordnik/wordnik-oss

39. Questions?