The SAP Cloud for Customer OData API Developer’s Guide com.zip

 # 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](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US/6cb5cd1ebe1c49d8b99c22afa29aa5d4.html) 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](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US). ## Table of Contents <!-- MarkdownTOC --> - [SAP Cloud for Customer OData API Developer's Guide](#sap-cloud-for-customer-odata-api-developers-guide) - [Table of Contents](#table-of-contents) - [What is OData protocol?](#what-is-odata-protocol) - [OData versions](#odata-versions) - [SAP Cloud for Customer (C4C) OData Services](#sap-cloud-for-customer-c4c-odata-services) - [OData Service Catalog](#odata-service-catalog) - [SAP Standard vs. Custom OData Services](#sap-standard-vs-custom-odata-services) - [OData Service Document](#odata-service-document) - [OData Service Metadata](#odata-service-metadata) - [Filtering Metadata](#filtering-metadata) - [Supported HTTP operations](#supported-http-operations) - [SAP Cloud for Customer Annotations](#sap-cloud-for-customer-annotations) - [Known Limitations](#known-limitations) - [Consuming C4C OData API](#consuming-c4c-odata-api) - [Supported Formats](#supported-formats) - [Authentication](#authentication) - [Technical / Integration User based Authentication](#technical--integration-user-based-authentication) - [CSRF Token](#csrf-token) - [Custom Headers](#custom-headers) - [Server side paging](#server-side-paging) - [Client side paging](#client-side-paging) - [Sample Java Client](#sample-java-client) - [Supported System Query Options](#supported-system-query-options) - [$batch](#batch) - [$expand](#expand) - [$filter](#filter) - [Filtering for delta changes](#filtering-for-delta-changes) - [$inlinecount](#inlinecount) - [$search](#search) - [ETag Support](#etag-support) - [Optimistic Concurrency Control with ETag](#optimistic-concurrency-control-with-etag) - [Sample Payloads](#sample-payloads) - [Licensing](#licensing) <!-- /MarkdownTOC --> ## What is OData protocol? [Open Data (OData) Protocol](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata) 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](http://www.odata.org/documentation/odata-version-2-0/). ## 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: ```http 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: ```http 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](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US/8e4220fa6dc943ef891fb3d0e91515d3.html). ### 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](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US/8e4220fa6dc943ef891fb3d0e91515d3.html) 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. ```http 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) ```http 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) ```http 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_. ```http 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](https://en.wikipedia.org/wiki/ISO_639-1). For example, to receive the UI labels in Turkish the HTTP request header should be set as below: ```http 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. ```http 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, c