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": "john@apiary.io", "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": "john@apiary.io" }, "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 john@apiary.io 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 | john@apiary.io | | 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: john@apiary.io - id: 67256f5bc - address (object)

No content

MSON is HUMAN FRIENDLY

MSON is MACHINE FRIENDLY

MSON is DATA

# User - name: John - email: john@apiary.io - toe_count: 10 (number) { "name": "John", "email": "john@apiary.io", “toe_count”: 10 }

MSON is SCHEMA

# User - name: John - email: john@apiary.io - 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: john@apiary.io - toe_count: 10 (number) … JSON Schema JSON HAL Siren …

MSON has INHERITANCE

# User - name: John - email: john@apiary.io - 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": "john@apiary.io", "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: john@apiary.io - 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/