OData Design Principles

July 26, 2012

BUILD ON HTTP, REST

• OData is a RESTful HTTP Protocol• Build on HTTP• Entities modeled as Resources• Relationships modeled as links• CRUD = POST, GET, PUT/PATCH, DELETE

• OData is Hypermedia-Driven• Service Document• Edit Links• Relationship Navigation• Actions/Functions in payload

• Enables loose coupling between clients and services

LEVERAGE EXISTING FORMATS

• Build on existing Formats• ATOM, JSON, XML

• Leverage built-in functionality appropriate to format where present• ATOM links, ids, etc.

• Leverage extensibility for functionality not part of format• Namespaces for control data, conventions

MODEL DRIVEN

• The Model defines the Contract• Defines Entity Sets, Entity Types, Functions

o Set of possible valid common requests are derived from the model according to well defined semantics and conventions for querying, updating, and invoking operations– Enabled client query string building

o Defines result shapes– Enables codegen of strongly typed objects at design time

• Improves semantic interoperability while providing the client the most flexibility in the requesting desired data

SIMPLICITY IS KEY

• Make it easy to implement over a broad variety of data sources• Incremental work for more advanced

functionality• Conventions and semantics over a well

defined model, common tools and libraries should make it easier to implement than defining a custom RESTful protocol.

CLIENT FOCUSED

• Define a simple to consume model that guides the client experience• Relationships rather than Foreign Keys• Inheritance rather than joins or descriminator

fields• De-normalize as appropriate

CONSISTENCY

• Consistency across the interface facilitates understanding and makes it easier to reuse code• Applying common principles makes the interface

predictable• Principle of least astonishment

• More advanced scenarios should not work differently than simple scenarios

REACH OVER RICH

• Make the common stuff available and simple across services for the greatest number of consumers• Don't try and define every possible feature of

every underlying storeo i.e., Don't try and implement all of TSQL

EXTENSIBLE

• Support advanced/custom scenarios through Extensibility• Metadata annotations for metadata extensibility• Instance annotations for data extensibility• Functions for query extensibility• Actions for CUD/Operational extensibility• Leverage Format-specific Extensibility

• Enable common, shared extensions for features outside of OData's core functionality

EXTENSIONS ARE WELL BEHAVED

• Extensions should be “opt-in”• Unless the client does something different,

behavior should be as defined in Core• Client libraries should not have to know

about extensions to work correctly

EXTENSIONS COMPOSE WELL

• Specific extensions should use common extensions for common concepts• i.e., Analytics extensions should use common

vocabularies for units, common display hints, etc.