8. oData

Architecture

OData is a protocol for building and consuming RESTful APIs.
Like REST, OData is based on HTTP, AtomPub, and JSON, using URIs to address and access data channel resources.

Resource Identification

OData uses URIs to identify resources.

For each OData service, whose root is abbreviated as http://host/service/, you can find the following fixed resources:

  1. Service Document
    The service document lists entity sets, functions, and individual items that can be retrieved. Clients can use the service document to navigate the model based on hypermedia. The service document is available at the root: http://host/service/.
  2. Metadata Document
    The metadata document describes the types, sets, functions, and actions understood by the OData service. Clients can use the metadata document to understand how to query and interact with objects in the service. The metadata document is available at http://host/service/$metadata.

Data Management

OData uses HTTP methods to specify operations on resources.

  1. GET: Retrieve data (collections, single objects, structural properties, navigation properties, streams, etc.).
  2. POST: Create new data.
  3. PUT: Update existing data by completely overwriting with a new object.
  4. PATCH: Update existing data by replacing only some fields.
  5. DELETE: Delete a record.

Useful links for reference:

  1. Explaining OData by SAP
  2. Official OData protocol documentation

oData V2 and V4

Ui5 natively supports both versions of oData.

For SAP onPremise — V2 (because the backend does not support anything else)

For CAP and other cloud solutions — V4.

Annotations for each oData version are different. So it’s important to know which version you are using. When reading documentation, check the section for your version.

For technical internal differences between the two protocol versions, see: https://1dsag.github.io/UI5-Best-Practice/odata/v2vsv4.html

Naming rules for entities and fields in oData

OData Entity Rule Good Example Bad Example
General Use UpperCamelCase SalesDocument SALESDOCUMENT
General No underscores PurchaseOrder Purchase_Order
General In English Order Zakaz
General No technical SAP names CompanyCode BUKRS
Entity names Only nouns CostCenter CostCenterF4
Entity names Only singular PurchaseOrder PurchaseOrderList
Entity names No operation names SalesOrder CreateSalesOrder
Sets Plural or with Set postfix PurchaseOrders, PurchaseOrderSet PurchaseOrder
Navigation Same as entity name if 1-1 relationship /OrderHead('1')/OrderItem('1') /OrderHead('1')/Header_Item('1')
Navigation Same as set name if 1-M relationship /OrderHead('1')/OrderItems /OrderHead('1')/Header_Item
Functions (V2)/Actions(V4) Use meaningful names BlockSalesOrder Block