Running Away from JSON (or what I learned building the OneNote API)
18
Running Away From JSON (or what I learned building the OneNote API) Gareth Jones API Architect Microsoft OneNote
-
Upload
gareth-jones -
Category
Software
-
view
265 -
download
0
description
API Design: Lessons learned building the OneNote API at Microsoft. Talk given at APIWorld 2014.
Transcript of Running Away from JSON (or what I learned building the OneNote API)
Running Away From JSON(or what I learnedbuilding the OneNote API)Gareth JonesAPI ArchitectMicrosoft OneNote
• Launched in 2003 on Windows• COM/XML client API
• Gradually grew platform support from 2010
• 2014 released Mac and Android tablet to complete platform line-up• Apps focused on cloud storage
• March 2014 REST API release
OneNote History
• OneNote client API XML schema <one:Outline > <one:Position x=\"120\" y=\"160\"/> <one:Size width=\"120\" height=\"15\"/> <one:OEChildren> <one:OE alignment=\"left\"> <one:T> <![CDATA[Sample Text]]> </one:T> </one:OE> </one:OEChildren> </one:Outline>
• Seems like it minimizes lossy ‘translations’
• Fragile to implementation change• More change means more translation• Or worse, breaking changes• Even worse, internals calcify to avoid breaking
change
Don’t ship your internals on the wire
• HTTP API• XML payload• RPC actions
OneNote API?
• Deal with team’s preconceptions• SOAP/RPC• JSON but RPC• REST zealot• We have XML on client, server should match
• Because XML is bad, JSON MUST be good• Right?
• JSON isn’t the only description language• But try not to invent your own
Level-set your religiosity
• HTTP REST API• Detailed JSON model of pages
OneNote API?
• Don’t design primarily based on product’s surface area
• Design for product’s key scenarios• Have a plan to expand to remaining area
• #1 scenario• Send a page of content to OneNote
• API users’ current mental models for similar tasks?• OneNote page mixture of rich text, images, tables
etc.• Industry represents that as HTML
APIs are scenario-driven too
• HTTP REST API• JSON model of options for html/text/images
OneNote API?
• Avoiding breaking changes = good• Adding fields = OK• Adding similar fields = confusing{ text=“Some plain text”, html=“<some html content>”, images = [ , , , ], tables = [ { table1 … }, { table2 … } ]}
• What happens?• If you need parse rules, reconsider
Know when to stop accretion
• HTTP REST API• HTML page content model
OneNote API?
• Beware the RFC zealot
• Tolerant on way in• Strict compliance on way out
• Look for and accept the most common errors
• It’s all about time to first successful API call
RFCs matter, but be generous
• HTTP REST API• HTML page content model• Relaxed multipart-MIME for adding images, PDFs
OneNote API?
• HTML model of Notebook hierarchy?<notebook><section1 /> <page 1> <html /> </page1><section 2 /></note book>
• Consistency vs JSON the right tool• Mixed content model is OK
Use the right tool for the job
• HTTP REST API• HTML page content model• Relaxed multipart-MIME for adding images, PDFs• JSON model for Notebook/Section hierarchy
OneNote API?
• Query language required to select items
• OData standard used across Microsoft~/sections?$filter title eq ‘My first section’
• Balancing act – Microsoft vs industry• Choose your predominant audience
• Sometimes there are only styles, not standards
Avoid not invented here
• HTTP REST API• HTML page content model• Relaxed multipart-MIME for adding images, PDFs• OData JSON model for Notebook/Section hierarchy• OData query language allows select, sort, expand
etc.
OneNote API V1.0
© 2013 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.
Q & A
