DATA IS YOUR API Z – @zdne Apiary.io

API Blueprint

# User [/user] ## Retrieve [GET] Retrieves the . + Response 200 (application/json) { "name": "John" }

No content

No content

API DESCRIPTION

API is INTERFACE to RESOURCES

RESOURCES are DATA

HOW DO YOU DESCRIBE DATA?

{ "name": "john", "email": "[email protected]", "id": "67256f5bc", "address": { "street": "325 Ninth Street", "city": "San Francisco", "state": "CA", "zip": "94103", "country": "United States" } }

{ "$schema": "http://json-schema.org/draft-04/schema#", "id": "/", "type": "object", "properties": { "name": { "id": "name", "type": "string", "default": "John" }, "email": { "id": "email", "type": "string", "default": "[email protected]" }, "id": { "id": "id", "type": "string", "default": "67256f5bc" }, "address": { "id": "address", "type": "object", "properties": { "street": { "id": "street", "type": "string", "default": "325 Ninth Street" }, "city": { "id": "city", "type": "string", "default": "San Francisco" }, "state": { "id": "state", "type": "string", "default": "CA" }, "zip": { "id": "zip", "type": "string", "default": "94103" }, "country": { "id": "country", "type": "string", "default": "United States" } } } } }

name type description example name string name of the user john email string user's email [email protected] id string unique id of the user 67256f5bc address object

| name | type | description | example | |:-------:|--------|-----------------------|----------------| | name | string | name of the user | john | | email | string | user's email | [email protected] | | id | string | unique id of the user | 67256f5bc | | address | object | | |

We can do better.

MSON github.com/apiaryio/mson

MARKDOWN SYNTAX for OBJECT NOTATION

# User - name: John - email: [email protected] - id: 67256f5bc - address (object)

No content

MSON is HUMAN FRIENDLY

MSON is MACHINE FRIENDLY

MSON is DATA

# User - name: John - email: [email protected] - toe_count: 10 (number) { "name": "John", "email": "[email protected]", “toe_count”: 10 }

MSON is SCHEMA

# User - name: John - email: [email protected] - toe_count: 10 (number) { "$schema": "http://json-schema.org/draft-04/schema#", "id": "/", "type": "object", "properties": { "name": { "id": "name", "type": "string" }, "email": { "id": "email", "type": "string" }, "toe_count": { "id": "toe_count", "type": "integer" } } }

MSON is FORMAT-AGNOSTIC

MSON is EVERY SERIALIZATION FORMAT you want* *currently supported are JSON-based formats and JSON Schema

# User - name: John - email: [email protected] - toe_count: 10 (number) … JSON Schema JSON HAL Siren …

MSON has INHERITANCE

# User - name: John - email: [email protected] - toe_count: 10 (number) # Customer (User) - orders (array) - order_count (number)

MSON has many ADVANCED FEATURES mixins, mutual exclusive properties, enumerations, sample values, default values, generics…

MSON is made to DESIGN DATA

MSON is made to define DOMAIN SEMANTICS

MSON is in API Blueprint

MSON + Content-Type = No JSON in API Blueprint

- Response 200 (application/json) { "name": "John", "email": "[email protected]", "id": "67256f5bc", "address": { "street": "325 Ninth Street", "city": "San Francisco", "state": "CA", "zip": "94103", "country": "United States", } } - Response 200 (application/json) - Attributes (User)

MSON brings DRY to API Blueprint

## User [/users/{user_id}] - Attributes - name: John - email: [email protected] - id: 67256f5bc - address (object) ### View a User Detail [GET] - Response 200 (application/json) - Attributes (User) ## User Collection [/users] ### List All Users [GET] - Response 200 (application/json) - Attributes (array[User])

No content

MSON is API ONLY

No content

We think you shouldn’t be writing JSON or JSON Schema save your time

DESCRIBE your DATA in a human readable, reusable and DRY way, once for all media types

API is your DATA your DATA are the API not URLs or other HTTP technical details

AVAILABLE TODAY at Apiary.io and APIBlueprint.org beta

API ♥ DATA github.com/apiaryio/mson Q&A @zdne, @apiaryio

No content

MIND SHIFT • Describe resource NOT representation • Define domain semantics • Reuse common semantics • Do NOT focus on technical details • URIs • representations • schema validations

API IS NOT … • API is not pretty URLs • API is not HTTP Verbs • API is not CRUD • API is not JSON

REST ARCHITECTURE • Client–server • Stateless • Cacheable • Layered system • Code on Demand (optional) • Uniform Interface • Identification of resources • Manipulation through representations • Self-descriptive messages • Hypermedia as the engine of the application state

REFERENCE • http://apiary.io • http://apiblueprint.org • https://github.com/apiaryio/mson • http://www.ics.uci.edu/~fielding/pubs/dissertation/ rest_arch_style.htm • https://devcenter.heroku.com/articles/platform-api- reference#account • https://developers.facebook.com/docs/graph-api/reference/user • https://stripe.com/docs/api/curl#customer_object • https://developer.github.com/v3/users/