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

Transcript

1. EASY DATA MODELING WITH MSON Emmanuel Paraskakis (@manp) VP of Product, Apiary
4. OBSERVATION #1 
 APIS ARE MOSTLY DATA Apiary users spend a lot of time thinking about modeling data
5. OBSERVATION #2 
 SOFTWARE PRODUCTS ARE MOSTLY DATA In my product career, I’ve spent a lot of time modeling data
6. 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
7. CAN YOU SEE THE PROBLEM? 
 same needs; different languages
8. BUT THEY ALL HAVE TO AGREE ON A PRECISE DEFINITION or their needs will not be met, 
 API projects will fail
9. 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
10. WE HAVE A SOLUTION! 
 Markdown Syntax
 for Object Notation (MSON)
11. 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
12. A TASK - JSON { "id": "42", "title": "Buy Milk" }
13. A TASK - JSON SCHEMA { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } } }
14. A TASK - MSON - id: 42 - title: Buy Milk
15. MARKDOWN • id: 42 • title: Buy Milk
16. SPEC 1. Values 2. Descriptions 3. Types 4. Inheritance
17. VALUES - id: 42 - title: Buy Milk
18. DESCRIPTIONS - id: 42 - Uniquely identifies task - title: Buy Milk - Task title
19. PRIMITIVE TYPES { "id": 42, "title": "Buy Milk", "complete": false } numeric required can be null a boolean
20. 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" ]
21. PRIMITIVE TYPES - id: 42 (number, required) - Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
22. NAMED TYPES # Task - id: 42 (number, required) - Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
23. STRUCTURE TYPES - id: 84 (number, required) - Uniquely identifies project - name: Shopping List (string, nullable) - Name of project - tasks (array[Task])
24. STRUCTURE TYPES { "id": 84, "name": "Shopping List", "tasks": [ { "id": 42, "title": "Buy Milk", "complete": false } ] }
25. 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" ] }
26. INHERITANCE # User - id: 1 (number, required) - Uniquely identifies user - name: Emmanuel Paraskakis (string, required) - Name of user - email: emmanuel@apiary.io (string, required) - User email # TeamMember (User) - team: Shoppers (required) - Team name - role: Dairy (nullable) - Role name
27. INHERITANCE { "id": 1, "name": "Emmanuel Paraskakis", "email": "emmanuel@apiary.io", "team": "Shoppers", "role": "Dairy" }
28. apiary.io • Collaboration • Documentation • Prototype (Mock) • Console • →JSON • →JSON Schema • Inspector • Automated Tests
29. 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
30. apiary.io emmanuel@apiary.io @manp QUESTIONS?
31. 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: emmanuel@apiary.io (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