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 store
o 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.