Euroclojure2014: Schema & Swagger - making your Clojure web APIs more awesome
-
Upload
metosin -
Category
Technology
-
view
2.204 -
download
0
description
Transcript of Euroclojure2014: Schema & Swagger - making your Clojure web APIs more awesome
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