Download - Scala & Swagger at Wordnik
Scala & Swagger at Wordnik
Tony Tam@fehguy
Agenda
•Who is Wordnik?
•Why bother with this Scala thing?
•What did we get from it?
•What is Swagger
•Why it should matter to you
Wordnik Tech Overview
•API based infrastructure
• Micro service oriented architecture
• Business by Scala, Java, MongoDB
• Beauty by Javascript, Ruby
•20M API calls daily
• Powered by Swagger, inside & out
•20B+ hot documents in MongoDB
Why Bother with Scala?
•Not just looking for next new thing
• “I was just getting good at ${language.name}!”
•Technology selection has consequences
• .net vs OSS
• Flash vs. HTML5
•Java is…
• Stable
• Fast
• Widely accepted
Why Bother with Scala?
•Look at the scenery
• One size does NOT fit all
• Rise of Ruby, Javascript, node.js, etc.
•Hey, they did lots of things right
• Focus on making things easy
So What is it?
•JVM-based language
• Started by Martin Odersky
•Functional & OO
•Typesafe
•Fully compatible with Java
Includes Dizzying Syntax
Java Pain Points
•DRY is difficult with Java
• Interfaces are great
• Implementation?
• Many ways to peel the onion!
•Easy to follow
• Often explosive LOC!
Example
•Our REST service
• Back-end returns different object implementations depending on operation
Example
•Many operations produce models with similar attributes
•Resulting in a mess
of classes
Example
•An Interface…
•An Implementation…
Example
•Another Impl…
Example
•And another…
Example
•Implementation is duplicated everywhere
•Annotations are duplicated everywhere
• Am I lazy to complain?
Consistency
Matters!
Simplified with Scala
•Objects can have Traits
• Like java interfaces + ruby mixins
• Creates “proper” subtypes
•Compiler built, concrete classes
• The “Word” trait…
• The corresponding impl…
Simplified with Scala
•More traits. Reuse these across your codebase!
•The other Impls:
Simplified with Scala
•Big deal?
• Just the beginning of the good stuff
•Scala syntax
• In Java, strict syntax is enforced
• In Scala: “it’s OK unless it’s not”
XML in Scala
•Support is baked in
• Declaring XML
XML in Scala
•Parsing XML is easy
Text Processing
•But first, the match statement
• Like switch:
Text Processing
•But much more powerful
Text Processing
•Pattern matching + “match” statement
• Extract name in different formats
Text Processing
(Erin,McKean)(Joe,Hyrkin)(Anthony,L.,Tam)Kumanan
Summary of Scala @ Wordnik
•Lost NONE of our Java codebase
•Code reuse is up
•Code consistency is up
•Flexibility is up
•LOC is down
•Readability is…
Why Swagger?
•Integration with REST APIs is troublesome and inconsistent
• Different vendors have different REST semantics
• Client libraries vary wildly by vendor, language
• Documentation for developers is an afterthought
• Input parameters, allowable values, models, responses are found via trial & error
•Internally a PITA
•YOUR API is too hard to develop against!
How Does it Work?
•Your server produces a Resource List
• All available APIshttp://petstore.swagger.wordnik.com/api/resources.json
“It’s like a sitemap for your
API!”
How Does it Work?
•Each API declares itself
• Available operations
• Parameters
• Type (path, query, body)
• Allowable values/data types
• Input/output models
• Error responses with descriptions
API Response
http://petstore.swagger.wordnik.com/api/pet.json
API Response
•Knowing input/output models is helpful!
Based on JSON
Schema (Draft)
http://tools.ietf.org/html/draft-zyp-json-schema-03
But what’s the benefit?
•A Sandbox!
Client Library Generation
•Code generation based on Resource Spec
• Template-based Framework
• Consume REST Methods, Models, Parameters
• Produce client libraries
•“Know before you go HTTP”
• Required values, fields are known by the client
•Only expose what’s allowed!
• Swagger filtering removes methods/models you don’t have access to
Client Library GenerationOrdinary dev access
Super user
access
Test Framework
•JSON-driven tests for your Client + API
Expected dataTest Suites
Test Framework
Easy to add
•For Java/Scala via JAX-RS…
• Add swagger-core.jar
• Annotate your models per your @Provider class
• Annotate your resources
Easy to add
•For node.js via express
• Require swagger.js
• Declare your swagger specs, models
• Could use AST/DSL to do automatically
• Add your operations, configure and start
Easy DIY
•The Swagger spec is Language Agnostic!
• ANY swagger-compliant server can…
• Use the Swagger client lib generator
• Use the test framework
• Use the sandbox UI
•More server support from Wordnik
• Play, Rails
•.net, others community developed
Where to go Next
•Try Swaggerswagger.wordnik.com
•See it in actiondeveloper.wordnik.com/docs
•Download the source/samplesswagger.wordnik.com/downloads
•Discuss itgroups.google.com/group/wordnik-api
#swagger_doc on freenode
Questions?