OData V4 and SAP Cloud Application Programming Model

DJ Adams, Developer Advocate at SAP

In this session we'll look at the intersection of OData V4 and the SAP Cloud Application Programming Model (CAP) which already supports many features.

The latest incarnation of OData is 4.01. This talk covers the more widely known and implemented 4.0 version.

1995 1996 1997 1998 1999 2000 2001 2002 2003 2004
|                   |                   |
MCF                 RSS                 Atom

2005 2006 2007 2008 2009 2010 2011 2012 2013 2014
|         |                                  |
RFC4287   RFC5023                            |
(format)  (protocol)                         |
          |                                  |
          OData (MS OSP)                     OData V4 (OASIS)

2015 2016 2017 2018 2019 2020 2021 2022
|
OData V4 (ISO/IEC)

See Monday morning thoughts: OData

Core specification components and related works

• Protocol (how it relates to HTTP)
• URL Conventions (what you can do with OData URLs)
• Common Schema Definition Language (metadata)

• ABNF Construction Rules (formal grammar definition)
• Core Vocabularies (Capabilities, Core and Measures)
• Formats (Atom and JSON) and Schemas (EDMX and EDM)

• Data Aggregation
• Temporal Data

Different document types denoting position in drafting, review and approval flow:

• Committee Note
• Committee Specification
• Public Review Draft
• Candidate OASIS Standard
• OASIS Standard

https://github.com/qmacro/odata-specs/blob/master/overview.md

Examples based on qmacro/odata-v4-and-cap

• Brand new system query option for cross-property text search
• See Part 2: URL Conventions section 5.1.7 System Query Option $search
• Available in CAP for Node.js and Java
• Use annotation @cds.search for more precise definitions - see Searching Textual Data

http://localhost:4004/main/Categories?$filter=contains(CategoryName,'products')

http://localhost:4004/main/Categories?$filter=contains(Description,'products')

vs

http://localhost:4004/main/Categories?$search=products

• Expanded entities can be filtered, ordered, paged, etc with a more composable nested syntax $expand=<navprop>(<system-query-option>;...)
• Already some support for key system query options, in particular $filter, $select and $orderby
• Deep dive: Part 4 - all things $filter

http://localhost:4004/main/Suppliers
  ?$select=CompanyName
  &$expand=Products(
    $orderby=UnitPrice;
    $filter=UnitsInStock gt 0;
    $select=ProductName,UnitPrice,UnitsInStock
  )

http://localhost:4004/filter.html#more-advanced-usage

(See first example "Suppliers and their stocked products, ordered by price")

• $count appended to a resource path -> raw scalar value
• $inlinecount as system query option

• $count is also now a system query option, replacing $inlinecount

http://localhost:4004/main/Products/$count

http://localhost:4004/main/Products?$count=true

• A committee specification level extension to V4 with early support in CAP
• Described in the document "OData Extension for Data Aggregation Version 4.0 (CS 02)"
• Implemented via the new $apply system query option, using:
  • Transformations (filter, groupby and aggregate supported currently)
  • Aggregation methods (min, max, sum, average etc)

http://localhost:4004/main/Products
  ?$apply=aggregate(
    UnitPrice with max as MostExpensive
)

• A committee specification level extension to V4 with early support in CAP

http://localhost:4004/main/Products?
  $apply=filter(Discontinued eq true)
         /groupby(
           (Category_CategoryID),
           aggregate(
             UnitsInStock with sum as TotalStock
            )
          )

See http://localhost:4004/filter.html#data-aggregation

• Custom aggregates can be defined with annotations - supported in CAP
• Virtual properties simplifying otherwise explicit and complex expressions

http://localhost:4004/main/Products
  ?$apply=aggregate(
    UnitsInStock with sum as TotalStock
  )

• Custom aggregates can be defined with annotations - supported in CAP
• Virtual properties simplifying otherwise explicit and complex expressions

• Annotations: https://github.com/qmacro/odata-v4-and-cap/blob/main/sample/srv/customaggregates.cds
• Metadata: http://localhost:4004/custom-aggregates/$metadata
• Result: http://localhost:4004/custom-aggregates/Products?$apply=aggregate(UnitsInStock)

• A neater way to represent a single entity at the service root
• Implement at the service layer with @odata.singleton

http://localhost:4004/main/Products
  ?$orderby=UnitPrice asc
  &$top=1

http://localhost:4004/main/Products?$orderby=UnitPrice asc&$top=1

vs

• Annotations: https://github.com/qmacro/odata-v4-and-cap/blob/main/sample/srv/singleton.cds
• Metadata: http://localhost:4004/singleton-example/$metadata
• Result: http://localhost:4004/singleton-example/BestBargain

• Clear semantics, can be bound or unbound
• Actions may have side effects, functions may not

• Metadata: http://localhost:4004/main/$metadata

• Bound: http://localhost:4004/main/Suppliers/1/Main.addressLine()
• Unbound: http://localhost:4004/main/randomProduct()

• Bound: https://github.com/qmacro/odata-v4-and-cap/blob/main/sample/bin/ba-discontinue
• Unbound: https://github.com/qmacro/odata-v4-and-cap/blob/main/sample/bin/ua-submitOrder

Examples based on SAP-samples/odata-basics-handsonsapdev

• Vocabularies and annotations have been refactored and greatly improved
• Standard and custom vocabularies

• From OASIS: Core, Measures, Capabilities, Validation, Aggregation, Authorization

• Described by a type: https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#deleterestrictionstype
• @readonly as sugar: https://cap.cloud.sap/docs/advanced/fiori#prefer-readonly-mandatory-
• Annotate entity: https://github.com/SAP-samples/odata-basics-handsonsapdev/blob/annotations/bookshop/srv/service.cds
• Result: http://localhost:4004/stats/$metadata

CAP does the right thing and implements the annotation semantic (returning 405 on DELETE request)

• Vocabularies and annotations have been refactored and greatly improved
• Standard and custom vocabularies

• From SAP: Analytics, CodeList, Common, UI and many more - see odata-vocabularies

• From the UI Vocabulary https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/UI.md
• https://github.com/SAP-samples/odata-basics-handsonsapdev/blob/annotations/bookshop/srv/index.cds
  • Separate annotations & definitions with annotate keyword
  • Extended syntax for complex expressions (UI: { ... })
• Result: http://localhost:4004/catalog/$metadata
• App: http://localhost:4004/webapp/index.html#browse-books

• OData Version 4.0 specifications (the core components):
  • Part 1: Protocol
  • Part 2: URL Conventions
  • Part 3: Common Schema Definition Language
• OASIS OData standards overview
• OData Vocabularies Version 4.0
• An overview and map of the OASIS Documents
• OData Published as an ISO Standard
• What's New in OData Version 4.0
• The CAP documentation section on Serving OData APIs
• Monday morning thoughts: OData
• RFC 4287 (The Atom Syndication Format)
• RFC 5023 (The Atom Publishing Protocol)
• Back to basics video series on OData (Hands-on SAP Dev)

A list of the most recent standards (with approval dates) taken from the OASIS OPEN list of standards relating to the Open Data Protocol

• OData Atom Format Version 4.0 (17 Nov 2013)
• OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01 (12 May 2020)
• OData Common Schema Definition Language (CSDL) XML Representation Version 4.01 (12 May 2020)
• OData Extension for Data Aggregation Version 4.0 (04 Nov 2015)
• OData Extension for Temporal Data Version 4.0 - CS 01 (04 Nov 2015)
• OData JSON Format v4.0 (24 Feb 2014)
• OData JSON Format v4.01 (12 May 2020)
• OData v4.0 (24 Feb 2014)
• OData v4.01 (23 Apr 2020)
• Repeatable Requests Version 1.0 (07 Jul 2020)