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?