Developer Guidelines

Client Errors

Following list describes common types of client errors on API calls that receive request bodies: All CDL web services provide a response object comprising a HTTP status code and optionally a response entity (e.g. a business partner). The response entities are described by the particular web method documentation. The following listing defines the meaning of HTTP status codes in the context of CDL web services:

Status CodeDescription
400 (Bad Request)The request cannot be fulfilled due to bad syntax.
401 (Unauthorized)Authentication is required and has failed or credentials were not provided in the HTTP header
404 (Not Found)The requested resource (e.g. a business partner) was not found
500 (Internal Server Error)An unexpected error occurred during request processing. This should not happen and should be reported to the CDL software team
503 (Service Unavailable)The service is currently unavailable

Storing data

Storing space typeDescription
WorkspaceAn abstract area where customers can work. It contains the client's Data Mirror, Data Storages, Data Sources, configurations, and API Keys.
Data StorageStorage dedicated for client's data. Multiple Data Storages can be created in the organization's workspace. Data stored in the Data Storage can not be shared with the CDQ community.
Data MirrorA special type of storage dedicated to client's data. Only one Data Mirror is created in the organization's workspace. Data Mirror can be shared with the CDQ community.
Data SourceA partition-like space. Multiple Data Sources can be created in the Data Storage or Data Mirror.

Features and Profiles

Endpoints provide features in order to enable configurability to optimize performance. Features are very specific to the endpoint, however, following generic features can be distinguished.

FeatureDescription
LAB_*Feature toggle that is used temporarily to activate/deactivate beta features. Do no use in production environments.
ENABLE_SETTINGSEnables that organizational and/or user settings are applied to configure the endpoint. For example, organization-wide configuration for data curation output languages.
SHOW _*Feature which add additional fields to the response object. By default, these fields are hidden in order to keep the payload low and to increase performance

For convenience, most common configurations of the features are provided in terms of profiles which also can be selected in the endpoint. If no profile or feature is selected explicitly, a default profile will always be applied. In most cases, consumers do not need to configure features or profiles - they may use the endpoints as-is.»


Pagination

Responses that return multiple items will be paginated to 50 items by default. You can specify further pages control with the following query parameter:

Query ParameterDescription
limitSets the page size of the request object
startAfterStart after the provided pagination ID. Leave empty for the first query. The response will contain a property nextStartAfter which need to be used for any subsequent queries until nextStartAfter is empty.

Paging over whole resource

The whole resource can be retrieved using endpoint supporting pagination. Reading loop should include page read endpoint call with startAfter property, filled with the content of nextStartAfter from the previous page read result. When nextStartAfter property is empty, then reading loop should finish processing.

Example

Copy
Copied
var startAfter = null do var page = resource.readPage(limit, startAfter) process(page) startAfter = page.nextStartAfter while (null != startAfter)

Rate Limiting

Rate limiting is per API Key. Default is 20 requests per second maximum.


Request Size Limiting

Payload size

For most CDQ's endpoints, the maximum acceptable payload size of the request is set to 10 MB.

Exceptions from this limit are gathered in below table:

EndpointRequest Size
Upsert Business Partner250 MB

Upload file size

The same Request Size Limit applies to uploading the file.


Schema

Blank fields are omitted and not includes as null in order to optimize payload sizes. All timestamps are returned to ISO 8601 format

attention

Implementation Guidelines Carefully read and follow our integration guideline S1: Safe consumption of responses.


TLS Certificates

When connecting to our API, it may be necessary for some particular clients to explicitly download and import the TLS certificate chain. Please download the certificate chain here:

Please note that the certificates are renewed every year and need to be updated in your certificate management (if available).


Versioning

Understanding version numbers

Each API or App release is uniquely identified by a version number. The structure of the version follows the standards of Semantic Versioning 2.0.

Format and example:

Copy
Copied
<MAJOR>.<MINOR>.0+<BUILD TAG> 25     .45     .0+202007747438
  • Major: Incremented when incompatible API changes are releases
  • Minor: Incremented when functionality or fixes are released in a backwards compatible manner
  • Build: Timestamp of the build

Each API or App has its own release cycle and thus its own dedicated version. Release notes are published here.

Incompatible API changes

Incompatible API changes include ("breaking changes"):

  • End-of-life of an endpoint
  • Removal of a property in the request/response model
  • Removal of an enum value in the request/response model

Versioning and release strategy

In order to support and operate multiple API versions in parallel, we apply the following versioning strategy:

Versioning through URI paths Endpoints include the major version number in order to provide two version in parallel. If no version number is provided, the version is v1. Example:
Copy
Copied
http://api.cdq.com/reference-data/rest/businesspartners/lookup http://api.cdq.com/reference-data/rest/businesspartners/v2/lookup
Features and fixes are provided to all previous releases If not stated explicetly otherwise, we provide features and fixes not only for the latest but also for all supported previous releases. Even though you may use a v1 endpoint, you still benefit from (non-breaking) features or fixes.

Tags

The following tags are used in the API documentation for quick reference to versions.

  • V1, V2, .. ,VX: Refers to the major version of an API
  • latest: Refers to the latest version of an API

tags.png

Version selector by tags

End-of-life

End of life of APIs or endpoints is communicated 1 year in advance to give every customer the neccessary time to upgrade.

Implementation

Schema

The following guidelines support developers to build rocket-solid client implementations.

S1: Safe consumption of API responses Be aware that in the API responsse blank fields are omitted and not included as null. Your client implementation needs to check if values are present in the payload before using them - otherwise your application may generate null pointer exceptions or similar.

Here is the example of two responses of the same API endpoint - however, in the second response we don't provide a lastPaymentDate as this information is null and hence omitted.
Response #1 - Field has a valueResponse #2 - Field has null value
Copy
Copied
{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  "lastPaymentDate" : "2021-18-45"
  "country" : "DE"
  ..
}
Copy
Copied
{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  // ATTENTION: field "lastPaymentDate" is null so it will not be part of the response
  "country" : "DE"
  ..
}
If you client implementation requires always the field lastPaymentDate in every response then Response #2 will definetely lead to an application error which needs to be avoided.

Specifications

Below table provide links to download CDQ APIs specification in JSON, YAML or WSDL format.

attention

WSDL format is delivered only for the latest Version.

API NameJSONYAMLWSDL
Bankaccount Data @ V1Download jsonDownload yaml-
Bankaccount Data @ V2Download jsonDownload yamlDownload wsdl
Data Clinic @ V1Download jsonDownload yamlDownload wsdl
Data Compliance @ V1Download jsonDownload yaml-
Data Curation @ V1Download jsonDownload yaml-
Data Curation @ V2Download jsonDownload yamlDownload wsdl
Data Exchange @ V1Download jsonDownload yaml-
Data Exchange @ V2Download jsonDownload yaml-
Data Exchange @ V3Download jsonDownload yaml-
Data Exchange @ V4Download jsonDownload yamlDownload wsdl
Data Matching @ V1Download jsonDownload yaml-
Data Matching @ V2Download jsonDownload yamlDownload wsdl
Data Validation @ V1Download jsonDownload yaml-
Data Validation @ V2Download jsonDownload yamlDownload wsdl
Reference Data @ V2Download jsonDownload yaml-
Reference Data @ V3Download jsonDownload yamlDownload wsdl
SAP ODM API @ V3Download jsonDownload yaml

Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!

Mail our developer-portal team: developer-portal@cdq.com