Search code examples
jsonodatastandardsatom-feedatompub

Summary of OData standard for a minimal, read-only implementation

The OData specification is long. Even the "OData Core" document is pretty long.

So, how about a condensed summary of what a read-only OData publisher needs to implement at a minimum?

Solution

  • I'll start. An OData service provides an HTTP endpoint that:

    • MUST understand "Accept" headers
    • MUST support Content-Type header, and MUST support ATOM format (optionally JSON)
    • MAY return a service document (list of collections) to GET / (10.1.1)
      • If ATOM (AtomPub?) format, the hierarchy is service/workspace/collection/title
    • MUST return descriptions of collections to requests like GET /Customers (10.2)
      • If ATOM, the hierarchy is feed/entry/content
    • MUST return descriptions of individual entities to requests like GET /Customers(3) (10.2.1)
    • MAY return individual properties of individual entities for requests like GET /Customers(3)/Name (10.2.2)
    • MUST make available a CSDL schema description wrapped in an EDMX document (10.1.2)
      • This SHOULD be available at /$metadata
    • MAY support any of these queries (10.2.3)
      • Filters (limit rows returned): Products?$filter=Price lt 10.00
      • Select (limit fields returned): Products?$select=Rating,ReleaseDate
      • Order-by: Products?$orderby=ReleaseDate asc, Rating desc
      • Top, skip: Products?$top=5&$skip=2
      • InlineCount (include an entity count): Products?$inlinecount=allpages
    • MUST (?) provide a list of relationships for an entity (10.2.4): Products(0)/$links/Orders
    • MUST provide an entity count (10.2.5): Products/$count
    • MAY support other formats with $format specifier (10.2.3.7)

    When an ATOM feed is returned (such as for a collection), it needs to conform to some OData conventions: http://www.odata.org/documentation/odata-v3-documentation/atom-format/ For example:

    • Types used are "edm:String" etc.
    • link elements are used generously
    • content elements either contain content inline (eg, text data), or link to it (eg, images, binary files) with src= attribute.

    When a JSON feed is returned, it similarly follows certain rules:

    URLs are encouraged to follow this scheme: