EASY DATA MODELING WITH MSON Emmanuel Paraskakis (@manp) VP of Product, Apiary 

No content

No content

OBSERVATION #1 
 APIS ARE MOSTLY DATA Apiary users spend a lot of time thinking about modeling data 

OBSERVATION #2 
 SOFTWARE PRODUCTS ARE MOSTLY DATA In my product career, I’ve spent a lot of time modeling data 

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 

CAN YOU SEE THE PROBLEM? 
 same needs; different languages 

BUT THEY ALL HAVE TO AGREE ON A PRECISE DEFINITION or their needs will not be met, 
 API projects will fail 

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 

WE HAVE A SOLUTION! 
 Markdown Syntax
 for Object Notation (MSON) 

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 

A TASK - JSON { "id": "42", "title": "Buy Milk" } 

A TASK - JSON SCHEMA { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } } } 

A TASK - MSON - id: 42 - title: Buy Milk 

MARKDOWN • id: 42 • title: Buy Milk 

SPEC 1. Values 2. Descriptions 3. Types 4. Inheritance 

VALUES - id: 42 - title: Buy Milk 

DESCRIPTIONS - id: 42 - Uniquely identifies task - title: Buy Milk - Task title 

PRIMITIVE TYPES { "id": 42, "title": "Buy Milk", "complete": false } numeric required can be null a boolean 

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

PRIMITIVE TYPES - id: 42 (number, required) - Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status 

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

STRUCTURE TYPES - id: 84 (number, required) - Uniquely identifies project - name: Shopping List (string, nullable) - Name of project - tasks (array[Task]) 

STRUCTURE TYPES { "id": 84, "name": "Shopping List", "tasks": [ { "id": 42, "title": "Buy Milk", "complete": false } ] } 

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

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 

INHERITANCE { "id": 1, "name": "Emmanuel Paraskakis", "email": "[email protected]", "team": "Shoppers", "role": "Dairy" } 

apiary.io • Collaboration • Documentation • Prototype (Mock) • Console • →JSON • →JSON Schema • Inspector • Automated Tests 

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 

apiary.io [email protected] @manp QUESTIONS? 

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