The Open Data Protocol (OData) is an open protocol, which allows the creation and consumption of queryable and interoperable RESTful APIs in a simple and standardized way. Retrieval and modification of data is done with URL based service calls. They can be easily build and used:
https://.../your_service/CustomerInvoiceCustomerInvoiceCollection?
$top=10&$skip=100&$select=ID,Date&orderby=Date desc&$filter=Status eq '2'
“select ID and Date for 10 Customer Invoices with status code 2, newest first beginning with the 100th invoice.”
Many frameworks or libraries make consumption of OData services transparent. The complete OData description is available on odata.org. OData responses are self-descriptive. They contain details about structure, types and URLs to access the single entities or children.
OData in SAP Business ByDesign
SAP Business ByDesign offers two main OData interfaces.
- OData for Analytics allows you to access all available Business Analytics reports.
- You request the report and provide the configuration/parameters via the URL, ByDesign processes the report and determines the results, and returns the report results as response to your request. This allows you to easily read data, that is covered by a report.
- Modeled OData Services based on Business Objects, that allow to read and to write data. You use the SAP Business ByDesign OData Services Modeler to easily design standard OData Services.
Modeled OData Services are easy to create and very flexible.
OData Examples
The complete OData description is available on odata.org. OData responses are self-descriptive. They contain details about structure, types and URL to access the single entities or children.
- The response of a $metadata is the description of the structure of the service, what the service exposes and how.
https://YOUR_SYSTEM/sap/byd/odata/cust/v1/your_service/$metadata
- Calling your service URL without any addition, returns a list of collections that can be accessed, usually one or more per node and/or field. Example:
https://YOUR_SYSTEM/sap/byd/odata/cust/v1/your_service/
- Accessing a collection URL returns the data for that collection, usually a list of according nodes. Every entry is returned, but paged by default.
.../your_service/EmployeeCollection
- Accessing a single entry URL returns the data of this entry, based on the key field.
.../your_service/EmployeeCollection('00163E01077402DE8DA61387E62AC195')
- By default responses are XML. Use $format to request responses in JSON:
..../your_service/EmployeeCollection('00163E01077402DE8DA61387E62AC195')?$format=json
There are a couple of functions available, which include:
- Select: Only return the specified fields
.../your_service/EmployeeCollection?$select=EmployeeID,GivenName,FamilyName
- Top: Only return specified number of entries, e.g. for paging:
.../your_service/EmployeeCollection?$top=10
- Skip: Return data skipping the specified number of entries, e.g. for paging
.../your_service/EmployeeCollection?$skip=100
- Orderby: Sort the result by one or more fields, ascending (asc, default) or descending (desc)
.../your_service/EmployeeCollection?$orderby=FamilyName,GivenName
- Filter: Only return entries that fulfill the filter condition. Operators (eq, gt, ...) are supported
.../your_service/EmployeeCollection?$filter=FamilyName eq 'Doe' and GivenName eq 'John'
- These functions can be combined with ampersand (‘&’). Example: select ID and Date for 10 Customer Invoices with status code 2, newest first starting from the 100th invoice.
.../your_service/CustomerInvoiceCustomerInvoiceCollection?$top=10&$skip=100&$select=ID,Date&orderby=Date desc&filter=Status eq '2'
OData Tips
Performance depends also on the complexity of the service and the data returned. It is obviously a difference, if only some fields of a Root node are returned, or if the OData service exposes data from other nodes as well.
- $select function is supported to only retrieve a subset of the field exposed by a service.
- $top and $skip functions are supported to only retrieve a slice of entities. By default, up to 1000 entries are returned. The response also states an URL to fetch the next set.
- $filter function is supported to restrict the retrieved entities to those meeting the criteria.
- $expand can be used selectively to only join data from interesting nodes if required. Multiple expands can be done with one request.
Care has to be taken if nodes are merged. If there is a 1:1 relationship between the nodes, OData Modeler allows to either create a collection (like for n:m relationships) or to merge the data directly into the father node.
- In the first case, a Father->Child relationship results in a ChildCollection that can be expanded, but does not need to. In addition the ChildCollection can be used independently, especially also filtered.
- In the second case the Child is merged into the Father data, always returning the Child data together with the Father, if not restricted with $select. This can be more convenient to use (especially if Father and Child data are usually retrieved together or if data can be directly filtered based on the merged fields), but might be slower, if the Child data is fetched without really being required.
While a hierarchy of nodes (like Root + Item + Party or multiple Items) can be created with one request, an update is limited to one entity.
Every entity to update requires a separate request. If multiple nodes were merged into an entity, they can be updated together with one request.
