Schema & Swagger���making your Clojure web APIs more awesome

EuroClojure 2014 Tommi Reiman

@ikitommi

Topics •  (Too) simple web api in Clojure •  Prismatic Schema •  Swagger •  Ring-swagger •  Compojure-api •  Fnhouse-swagger •  Wrapup

(Too) simple web api in Clojure

D

git  clone  h,ps://github.com/ikitommi/euroclojure2014.git    

The sausage •  Id •  Name •  (Length) •  (Description) •  Origin – Country –  (City)

h,p://www.swe

etpoland.com/    

How do I program with sausages?

Java Sausage

Scala Sausage

Clojure Sausage?

Help  me!!  

Clojure Sausage?

A  Schema  is  a  Clojure(Script)  data  structure  describing  a  data  shape,  which  can  be  used  to  document  and  validate  func=ons  and  data.  

h,ps://github.com/prismaAc/schema  

Schema Sausage?

Schema Sausage?

Sc validation

Bydgoszcz & Tampere

h,p://en.wikipedia.org/wiki/Bydgoszcz     h,p://kuvat2.huuto.net/f/4f/1cdb0858b03c69122e9c06f9554a2-­‐orig.jpg    

Sc elements

Sc functions

perf

perf

“For  now  our  pragmaAc  soluAon  is  to  only  turn  on  validaAon  at  key  boundaries  in  producAon  code  

(using  :always-­‐validate),  and  only  check  the  remaining  asserAons  in  tests.    In  pracAce  this  seems  to  

catch  nearly  all  the  issues,  without  causing  any  performance  

problems.”          -­‐  Jason  Wolfe  

Sc coercion

Coerce!  Coerce!  

Sc goodies •  Double schema •  Schema selectors •  Generative Schema •  Schema-tools •  Contribs •  Ring-Swagger

Sc goodies Double  schema  

Sc goodies Schema  selectors  

Sc goodies

h,ps://gist.github.com/davegolland/3bc4277fe109e7b11770    

GeneraAve  Schema  

Sc goodies

h,ps://github.com/PrismaAc/om-­‐tools    

Om-­‐tools  

Sc goodies

h,ps://github.com/sfx/schema-­‐contrib      

Contribs  

h,ps://github.com/cddr/integrity    

Sc goodies

h,ps://github.com/metosin/ring-­‐swagger    

Ring-­‐Swagger  

Swagger

Swagger •  a specification and complete framework implementation for

describing, producing, consuming, and visualizing RESTful web services –  https://helloreverb.com/developers/swagger

•  Existing adapters for most common web stacks •  Clojure Libs

–  Octohipster (https://github.com/myfreeweb/octohipster) –  Swag (https://github.com/narkisr/swag) –  Ring-Swagger

•  Compojure-Api (https://github.com/metosin/compojure-api) •  Fnhouse-swagger (https://github.com/metosin/fnhouse-swagger)

Resource listing

Api declarations

(JSON) Schema definitions

Swagger UI

Swagger UI

Code-gen •  Client generators –  Scala, Flash, Java, Objc, PHP, Python, Python3, Ruby

•  Javascript via swagger-js •  Also server-stub generators … no clojure-support yet (anyone?)

Swagger-socket

h,ps://github.com/wordnik/swaggersocket  

Swagger editor

Swagger 2.0

coming  up.  

Ring-Swagger

Ring-Swagger •  Swagger implementation for Ring –  https://github.com/metosin/ring-swagger –  Based on Schema for data models & coercion

•  Extendable mappings of Schemas to JSON Schemas •  Symmetric parsers for common types (inc. Dates, DateTimes) •  Add-ons (coercers, predicates, tools)

–  Provides Swagger spec endpoints as Ring routes •  Resource-listing, Api-declarations, Swagger-UI

–  Independent to routing-libs •  Currently bindings exist to Compojure-Api and fnHouse

Ring-Swagger

>  

Ring-Swagger

Ring-Swagger

Ring-Swagger

Ring-Swagger

...    should  be  easier  to  extend.  

Ring-Swagger-UI •  Jar-packaged version of the Swagger-ui

–  https://github.com/metosin/ring-swagger-ui

So, where is my���Sausage API?

Compojure-api

Compojure-Api •  An extendable web api lib on top of Compojure –  https://github.com/metosin/compojure-api –  Macros & middlewares with good defaults –  Schema-based models & coercion –  Swagger docs

Restructured handlers

Restructured handlers

Restructured handlers

Restructured handlers

DIY  :for-­‐roles  [:admin  :user]  

Sausage API, take one

Sausage API, take one

?  

D

•  Macro-fu to reverse-engineer the route tree at macro-expansion time –  No runtime penalty –  Static routes (no ad-hoc hypermedia)

•  Storing compiled route tree in 1)  Evil Mutable State, part1: globally side-effecting macro 2)  Evil Mutable State, part2: macro-filled global atom 3)  Current: Namespace cluttering local Var 4)  Next up: Dynamic Var?

Route Resolution

Route Resolution: Macro-peeling

Route Resolution: Macro-peeling

Route Resolution: Macro-peeling

Swagger it.

D

Try it.

fnhouse

fnhouse •  Fnhouse is a library that

builds on top of ring to provide a concise way to write web handlers safely, readably, without global variables, without repeating yourself, and with hooks to do much more.

•  https://github.com/Prismatic/fnhouse

fnhouse •  Defnks with metadata è annotated handler –  Builds on schema & plumbing

•  Bootstrap: collect defnks & wrap to ring-handlers

•  No global state

fnhouse

h,ps://www.youtube.com/watch?v=VEDLSvSSMSk&index=27&list=PLZdCLR02grLp__wRg5OTavVj4wefg69hM    

fnhouse-swagger •  https://github.com/metosin/fnhouse-swagger •  fnhouse.swagger (54 loc) •  bootstrap it:

Final chapter

Schema & Swagger •  Prismatic Schema is an awesome tool – Describe, validate & coerce your data

•  Swagger to publish out api descriptions •  Building on top of ring-swagger: – Compojure-api è declarative web apis –  Fnhouse-swagger è meta-data done right – YourFavouriteWebLib è just do it (& poke us).

Next things @ Metosin •  Ring-Swagger –  Make feature complete (+Swagger 2.0)

•  Compojure-Api –  Cleanup route-peeling –  Ring-middleware-format –  Repl-tools?

•  Help others to adapt •  kekkonen.io –  CQRS-lib

Thanks.  @metosin  @ikitommi