Slide 1

Slide 1 text

DATA IS YOUR API Z – @zdne Apiary.io

Slide 2

Slide 2 text

API Blueprint

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

API DESCRIPTION

Slide 7

Slide 7 text

API is INTERFACE to RESOURCES

Slide 8

Slide 8 text

RESOURCES are DATA

Slide 9

Slide 9 text

HOW DO YOU DESCRIBE DATA?

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

{ "$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" } } } } }

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

| 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 | | |

Slide 14

Slide 14 text

We can do better.

Slide 15

Slide 15 text

MSON github.com/apiaryio/mson

Slide 16

Slide 16 text

MARKDOWN SYNTAX for OBJECT NOTATION

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

No content

Slide 19

Slide 19 text

MSON is HUMAN FRIENDLY

Slide 20

Slide 20 text

MSON is MACHINE FRIENDLY

Slide 21

Slide 21 text

MSON is DATA

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

MSON is SCHEMA

Slide 24

Slide 24 text

# 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" } } }

Slide 25

Slide 25 text

MSON is FORMAT-AGNOSTIC

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

MSON has INHERITANCE

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

MSON is made to DESIGN DATA

Slide 32

Slide 32 text

MSON is made to define DOMAIN SEMANTICS

Slide 33

Slide 33 text

MSON is in API Blueprint

Slide 34

Slide 34 text

MSON + Content-Type = No JSON in API Blueprint

Slide 35

Slide 35 text

- 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)

Slide 36

Slide 36 text

MSON brings DRY to API Blueprint

Slide 37

Slide 37 text

## 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])

Slide 38

Slide 38 text

No content

Slide 39

Slide 39 text

MSON is API ONLY

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

AVAILABLE TODAY at Apiary.io and APIBlueprint.org beta

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

No content

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

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/