Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Data is your API

Z
April 16, 2015

Data is your API

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

https://github.com/apiaryio/mson

Z

April 16, 2015
Tweet

More Decks by Z

Other Decks in Programming

Transcript

  1. # User [/user] ## Retrieve [GET] Retrieves the . +

    Response 200 (application/json) { "name": "John" }
  2. { "name": "john", "email": "[email protected]", "id": "67256f5bc", "address": { "street":

    "325 Ninth Street", "city": "San Francisco", "state": "CA", "zip": "94103", "country": "United States" } }
  3. { "$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" } } } } }
  4. <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>[email protected]</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>
  5. | 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 | | |
  6. # User - name: John - email: [email protected] - toe_count:

    10 (number) { "name": "John", "email": "[email protected]", “toe_count”: 10 }
  7. # 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" } } }
  8. # User - name: John - email: [email protected] - toe_count:

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

    10 (number) # Customer (User) - orders (array) - order_count (number)
  10. - 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)
  11. ## 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])
  12. API is your DATA your DATA are the API not

    URLs or other HTTP technical details
  13. MIND SHIFT • Describe resource NOT representation • Define domain

    semantics • Reuse common semantics • Do NOT focus on technical details • URIs • representations • schema validations
  14. API IS NOT … • API is not pretty URLs

    • API is not HTTP Verbs • API is not CRUD • API is not JSON
  15. 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
  16. 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/