Data is your API

Launch of MSON – Markdown syntax for describing and modeling data (structures).

https://github.com/apiaryio/mson

Transcript

1. DATA IS YOUR API Z – @zdne Apiary.io
2. API Blueprint
3. # User [/user] ## Retrieve [GET] Retrieves the . + Response 200 (application/json) { "name": "John" }
6. API DESCRIPTION
7. API is INTERFACE to RESOURCES
8. RESOURCES are DATA
9. HOW DO YOU DESCRIBE DATA?
10. { "name": "john", "email": "john@apiary.io", "id": "67256f5bc", "address": { "street": "325 Ninth Street", "city": "San Francisco", "state": "CA", "zip": "94103", "country": "United States" } }
11. { "$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" } } } } }
12. <table> <tr> <th>name</th> <th>type</th> <th>description</th> <th>example</th> </tr> <tr> <td>name</td> <td>string</td> <td>name of the user</td> <td>john</td> </tr> <tr> <td>email</td> <td>string</td> <td>user's email</td> <td>john@apiary.io</td> </tr> <tr> <td>id</td> <td>string</td> <td>unique id of the user</td> <td>67256f5bc</td> </tr> <tr> <td>address</td> <td>object</td> <td></td> <td></td> </tr> </table>
13. | 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 | | |
14. We can do better.
15. MSON github.com/apiaryio/mson
16. MARKDOWN SYNTAX for OBJECT NOTATION
17. # User - name: John - email: john@apiary.io - id: 67256f5bc - address (object)
19. MSON is HUMAN FRIENDLY
20. MSON is MACHINE FRIENDLY
21. MSON is DATA
22. # User - name: John - email: john@apiary.io - toe_count: 10 (number) { "name": "John", "email": "john@apiary.io", “toe_count”: 10 }
23. MSON is SCHEMA
24. # 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" } } }
25. MSON is FORMAT-AGNOSTIC
26. MSON is EVERY SERIALIZATION FORMAT you want* *currently supported are JSON-based formats and JSON Schema
27. # User - name: John - email: john@apiary.io - toe_count: 10 (number) … JSON Schema JSON HAL Siren …
28. MSON has INHERITANCE
29. # User - name: John - email: john@apiary.io - toe_count: 10 (number) # Customer (User) - orders (array) - order_count (number)
30. MSON has many ADVANCED FEATURES mixins, mutual exclusive properties, enumerations, sample values, default values, generics…
31. MSON is made to DESIGN DATA
32. MSON is made to define DOMAIN SEMANTICS
33. MSON is in API Blueprint
34. MSON + Content-Type = No JSON in API Blueprint
35. - 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)
36. MSON brings DRY to API Blueprint
37. ## 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])
39. MSON is API ONLY
41. We think you shouldn’t be writing JSON or JSON Schema save your time
42. DESCRIBE your DATA in a human readable, reusable and DRY way, once for all media types
43. API is your DATA your DATA are the API not URLs or other HTTP technical details
44. AVAILABLE TODAY at Apiary.io and APIBlueprint.org beta
45. API ♥ DATA github.com/apiaryio/mson Q&A @zdne, @apiaryio
47. MIND SHIFT • Describe resource NOT representation • Define domain semantics • Reuse common semantics • Do NOT focus on technical details • URIs • representations • schema validations
48. API IS NOT … • API is not pretty URLs • API is not HTTP Verbs • API is not CRUD • API is not JSON
49. 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
50. 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/