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

Easy Data Modeling with MSON

paraskakis
November 04, 2016

Easy Data Modeling with MSON

MSON is a Markdown language for Data Modeling. Used with API Blueprint to create compact, readable API Descriptions. Presented at API Strategy & Practice conference, Boston, November 2016

paraskakis

November 04, 2016
Tweet

More Decks by paraskakis

Other Decks in Programming

Transcript

  1. OBSERVATION #1 
 APIS ARE MOSTLY DATA Apiary users spend

    a lot of time thinking about modeling data
  2. OBSERVATION #2 
 SOFTWARE PRODUCTS ARE MOSTLY DATA In my

    product career, I’ve spent a lot of time modeling data
  3. WHERE DO DATA MODELS COME FROM? • DBAs, Devs: SQL/ORM

    schemas • Architects: ER diagrams and the like • Business users: spreadsheets & documents • API devs: API definitions, JSON Schema • Front-end folks: Core Data, GraphQL schemas
  4. BUT THEY ALL HAVE TO AGREE ON A PRECISE DEFINITION

    or their needs will not be met, 
 API projects will fail
  5. ALL STAKEHOLDERS NEED A COMMON LANGUAGE: • Accessible to techies

    and business people • Usable by machines • Broad and articulate enough to
 describe most data models • Independent of implementation
 (defer architecture decisions) • DRY - duh
  6. https://github.com/apiaryio/mson • Based on Markdown - not a `{` to

    be seen • Parsable, Open Source Spec • Broad enough:
 Used by Apiary users this past year (7%) • Converts to JSON Schema (we’re in the API biz) …anything else you’d like in the future! • Encourages reuse
  7. A TASK - JSON SCHEMA { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object",

    "properties": { "id": { "type": "string" }, "title": { "type": "string" } } }
  8. PRIMITIVE TYPES { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "id":

    { "type": "number", "description": "Uniquely identifies task" }, "title": { "type": [ "string", "null" ], "description": "Task title" }, "complete": { "type": "boolean", "description": "Completion Status" } }, "required": [ "id" ]
  9. PRIMITIVE TYPES - id: 42 (number, required) - Uniquely identifies

    task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
  10. NAMED TYPES # Task - id: 42 (number, required) -

    Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
  11. STRUCTURE TYPES - id: 84 (number, required) - Uniquely identifies

    project - name: Shopping List (string, nullable) - Name of project - tasks (array[Task])
  12. STRUCTURE TYPES { "id": 84, "name": "Shopping List", "tasks": [

    { "id": 42, "title": "Buy Milk", "complete": false } ] }
  13. STRUCTURE TYPES { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "id":

    { "type": "number", "description": "Uniquely identifies project" }, "name": { "type": [ "string", "null" ], "description": "Name of project" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Uniquely identifies task" }, "title": { "type": [ "string", "null" ], "description": "Task title" }, "complete": { "type": "boolean", "description": "Completion Status" } }, "required": [ "id" ] } } }, "required": [ "id" ] }
  14. INHERITANCE # User - id: 1 (number, required) - Uniquely

    identifies user - name: Emmanuel Paraskakis (string, required) - Name of user - email: [email protected] (string, required) - User email # TeamMember (User) - team: Shoppers (required) - Team name - role: Dairy (nullable) - Role name
  15. apiary.io • Collaboration • Documentation • Prototype (Mock) • Console

    • →JSON • →JSON Schema • Inspector • Automated Tests
  16. THANK YOU! • MSON OSS spec/parsers - please contribute! •

    Can be read/written by all - collaboration • Focus on getting semantics right • Format-independent • Try MSON today on apiary.io
  17. FORMAT: 1A HOST: http://polls.apiblueprint.org/ # Project Management API Demo API

    for MSON Conference talk Basic Project Management including tasks and team members ## Tasks [/tasks] A task can have a team member assigned to it. It can also be complete or incomplete ### List all [GET] - Response 200 (application/json) - Attributes (array[Task], fixed-type) ## Task [/tasks/{id}] ### Retrieve a Task [GET] - Response 200 (application/json) - Attributes (Task) ## Projects [/projects] A project is a named collection of tasks ### List all [GET] + Response 200 (application/json) - Attributes (array[Project], fixed-type) ## Project [/projects/{id}] ### Retrieve a Project [GET] + Response 200 (application/json) - Attributes (Project) ## TeamMember [/teammembers] A Team Member inherits from a User ### List all [GET] + Response 200 (application/json) - Attributes (array[TeamMember], fixed-type) ## TeamMember [/teammembers/{id}] - Attributes (User) - team: Shoppers (required) - Team name - role: Dairy (nullable) - Role name ### Retrieve a TeamMember [GET] + Response 200 (application/json) - Attributes (TeamMember) # Data Structures ## User - id: 1 (number, required) - Uniquely identifies user - name: Emmanuel Paraskakis (string, required) - Name of user - email: [email protected] (string, required) - User email ## Task - id: 42 (number, required) - Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status - teamMemberId: 1 (number) - Must exist as a Team Member ## Project - id: 84 (number, required) - Uniquely identifies project - name: Shopping List (string, nullable) - Name of project - tasks (array[Task], fixed-type) SAMPLE API BLUEPRINT (67 LINES) http://docs.apistratmsondemo.apiary.io https://github.com/APIStratDemo/msonapi