Important Notice

This public repository is read-only and no longer maintained.

SAP Cloud for Customer OData API Developer's Guide

The SAP Cloud for Customer OData API Developer’s Guide complements the SAP Cloud for Customer OData API Reference with usage details and samples for SAP Cloud for Customer OData API in a format that is most convenient to developers. Furthermore, it also covers known restrictions and limitations of the SAP Cloud for Customer OData API.

For a brief introduction to SAP Cloud for Customer OData API, please refer to SAP Cloud for Customer OData API Documentation.

Table of Contents

<!-- MarkdownTOC -->

• SAP Cloud for Customer OData API Developer's Guide
  • Table of Contents
  • What is OData protocol?
    • OData versions
  • SAP Cloud for Customer (C4C) OData Services
    • OData Service Catalog
    • SAP Standard vs. Custom OData Services
    • OData Service Document
    • OData Service Metadata
      • Filtering Metadata
    • Supported HTTP operations
    • SAP Cloud for Customer Annotations
    • Known Limitations
  • Consuming C4C OData API
    • Supported Formats
    • Authentication
      • Technical / Integration User based Authentication
    • CSRF Token
    • Custom Headers
    • Server side paging
    • Client side paging
    • Sample Java Client
    • Supported System Query Options
      • $batch
      • $expand
      • $filter
        • Filtering for delta changes
      • $inlinecount
      • $search
    • ETag Support
      • Optimistic Concurrency Control with ETag
  • Sample Payloads
  • Licensing

<!-- /MarkdownTOC -->

What is OData protocol?

Open Data (OData) Protocol is an OASIS standard that defines best practices for building and consuming RESTful APIs. It is based on HTTP protocol and provides metadata for the entities it exposes and their relationships. In some ways, it is similar to SQL for a relational database system (RDBMS) as it provides querying options such as filtering, ordering results, support for pagination, number of records and more. It supports both XML (Atom) and JSON formats for querying and modifying data.

For more information on OData please refer to http://www.odata.org where you can find detailed documentation and tutorials.

OData versions

SAP Cloud for Customer, specifically, supports the V2.0 of the OData protocol (with some additional enhancements and a few limitations), you can read the details of OData V2 here.

SAP Cloud for Customer (C4C) OData Services

You can try the examples shown in this document by accessing the OData API of your SAP Cloud for Customer (C4C) tenant using the following URL pattern:

https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/v1/odataservicecatalog/ODataServiceCollection

where myNNNNNN is the name of your tenant.

OData Service Catalog

OData Service Catalog contains the list of available OData Services in the corresponding C4C tenant. In order to get the list of available OData services in your C4C tenant use the following URL:

https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/v1/odataservicecatalog/ODataServiceCollection

The catalog service returns both standard OData services delivered by SAP as well as the custom services that you may have modeled in your tenant using the OData Service Explorer.

SAP Standard vs. Custom OData Services

SAP Cloud for Customer provides a standard OData API. In addition, SAP Cloud for Customer also allows customers to build their own (custom) OData services based on the predefined business objects in the solution.

OData Service Explorer is a key user tool that allows exploring and testing SAP provided OData API as well as building custom services.

Standard and custom OData services offer the same capabilities and, are subjected to the same restrictions.

The following URL pattern differetiates the Standard and Custom OData services.

• Standard services - https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/v1/....
• Custom services - https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/cust/v1/...

OData Service Document

OData service document contains the list of OData entities (a.k.a. collections) contained within that OData service. In order to retrieve the complete list of entity sets included in C4C OData service, you can open the following URL in your browser.

https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/v1/c4codataapi/

where myNNNNNN is the name of your C4C tenant. (Please note that ‘/’ character at the end of the URI is required!)

OData Service Metadata

OData service metadata is retrieved via the following URL. (ObjectID as the key)

https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/v1/c4codataapi/$metadata

OData service metadata is retrieved via the following URL. (User-friendly ID as the key)

https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/uid/v1/c4codataapi/$metadata.

Labels for the entities and their properties can be retrieved by appending the query parameter sap-label=true.

https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/v1/c4codataapi/$metadata?sap-label=true

To receive the UI labels in a particular language HTTP header Accept-Language can be used. Prefered language code can be set based on ISO 639-1.

For example, to receive the UI labels in Turkish the HTTP request header should be set as below:

Accept-Language:tr

Filtering Metadata

OData service metadata can be filtered for specific EntityTypes (including all dependent EntityTypes) using the $filter query parameter.

For example the following request will return the metadata for ServiceRequest and Opportunity EntityTypes.

https://myNNNNNN.crm.ondemand.com/sap/c4c/odata/v1/c4codataapi/$metadata?$filter=ServiceRequest,Opportunity

Supported HTTP operations

C4C OData API supports the following OData/HTTP operations:

Operation | Description ----------|------------ GET | Used to retrieve a single entity instance or multiple entity instances POST | Used to create entity instances PUT | Used to completely replace/overwrite and existing entity instance PATCH | Used to replace/overwrite existing entity instance. The key difference between PUT and PATCH is that PUT overwrites the complete entity whereas PATCH only updates only attributes of the entity that are part of the payload DELETE | Used to delete an entity record $batch | Used to perform multiple query, create, update and delete operations with explicit transaction boundaries specified via Changesets as a part of the payload Deep Insert | Used with POST. Allows the creation of complete entity (header entry, child entries etc) with a single POST request

SAP Cloud for Customer Annotations

Following table describes the OData Framework behavior as of the November, 2018 release (1811).

|Annotation|Definition|Framework Behaviour| |----------|----------|-------------------| |sap:creatable = true|Property is relevant while creating a new record|OData Framework passes the value in the payload to the Business Object.| |sap:creatable = false|Property is NOT relevant for creating a new record|OData Framework raises an error if it receives a value for the property.| |sap:updatable = true|Property is relevant while updating a record|OData Framework passes the value in the payload to the Business Object.| |sap:updatable = false|Property is NOT relevant while updating a record|OData framework raises an error if the value is different from the one that exists in the Business Object.| |sap:filterable = true|The property can be used in $filter query parameter|OData Framework passes the filter value to the Business Object.| |sap:filterable = false|filterable = false|If $filter is used on that property OData framework raises an error| |c4c:context-property|The annotation provides the context for the property|E.g. Country is the context for the property RegionCode (i.e. State).|

Exception:

• In an POST (create) call, if a property has the attributes sap:creatable = false and Nullable = false (usually the case for ObjectID property as the value is auto-generated), OData framework will silently ignore the provided value.
• During a PUT/PATCH (update) call, values passed for ETag and Code Descriptions (e.g. StatusCodeText, CountryCodeText, etc.) will be silently ignored.

Note: The "Nullable" attribute indicates if the underlying field in the database allows n