G R E E N H O U S E . IO

Escape from the Tower of Babelor Using JSON-Schema to Enforce API Contracts

@mboufford - Mike Boufford, VP of Engineering at Greenhouse

What we’ll talk about

Primarily• Foxclores• Luzodins• Maozblitzers

But, also!• Norristronomy*• Fuffapesterinos• and of course, Hawkoons

I’ll presume that you’re all familiar with those terms?

Our APIs are all speaking a Glossopoeia!

A brief history of Schemata

• Schema comes from the Greek skhēma which translates to “form”

• The great German philosopher Kant took the term to mean “a conception of what is common to all members of a class"

1996: The Internet’s Rumspringa

D o u g l a s C r o c k f o r dDiscoverer of JSON and opinionated linter

{ something: “Blargh!” }

“Hey! Look what I found! We can

use this to send data on the

Internets!”

:-(

Um…Now I have to write adapters for everything I receive from anyone else, forever and ever.On the upside: #jobsecurity!

We now live in a world that is hostile to schemata

Stop the insanity!Itigil ni ito pagkabaliw Hayaan.

এর এই পাগলািম বn করা যাক .

Давайце спынім гэта вар'яцтва .

让我们停⽌止这种疯狂。

. בואו נעצור הטירוף הזה

ဒ" #$%သ'ပ)*ခင)% ကiuရပ)တ2)3 4ကကuန)အ73။Pojďme se zastavit toto šílenství .

. اس پاگلپن کو روکنے کے ہیں

First Step:

Teach people JSON-Schema

1JSON-Schema is a composable JSON-based schema language. It looks like this:

{

‘$schema’: ‘http://foo.com/person-01/schema’,

‘type’: ‘object’,

‘properties’: {

‘first_name’: { ‘type’: ‘string’ },

‘last_name’: { ‘type’: ‘string’ }

},

‘required’: [ ‘first_name’, ‘last_name’ ]

}

Composability {

‘$schema’: ‘http://foo.com/user-01/schema’,

‘type’: ‘object’,

‘properties’: {

‘user_id’: { ‘type’: ‘number’ },

‘person’: {

‘$ref’: ‘http://foo.com/person-01/schema’

}

},

‘required’: [ ‘user_id’, ‘person’ ]

}

Keeping things DRY

Simple{ ‘http_status_code’: { ‘type’: ‘string’ } }

Validation{ ‘http_status_code’: {

‘type’: ‘string’,

‘pattern’: ‘^[0-9]{3}$’

} }

Validation { ‘http_status_code’: {

‘type’: ‘number’,

‘enum’: [ 200, 403, 500 ]

} }

Part Deux

{ ‘http_status_code’: 500 }

Automated API Tests

JSON Hyper-Schema!

Enforcing RESTfulnessAnd we ain’t talking about nap time.

e.g., {

"href": “/apples“,

"method": "POST",

"rel": "self",

"targetSchema": {

"$ref": “http://foo.com/apple-schema#",

}

}

HYPER! AHHH!

So Dang EZ! What’s the catch?

Thank you.