Share
Embed
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
Emmanuel Paraskakis
November 04, 2016
Transcript
31 slides
-
EASY DATA MODELING WITH MSON Emmanuel Paraskakis (@manp) VP of
Product, Apiary -
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 -
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 -
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 SCHEMA { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object",
"properties": { "id": { "type": "string" }, "title": { "type": "string" } } } -
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 -
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