Developer Guidelines

Status and Error Codes

The following list describes common types of client statuses on API calls that receive request bodies: All CDQ Cloud Platform services provide a response object comprising an 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 CDQ Cloud Platform services:

Status 200XXXXX

Status 201XXXXX

Status 400XXXXX

Status 404XXXXX

Status 429XXXXX

Status 500XXXXX

Status 503XXXXX

Storing data

Features and Profiles

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

For convenience, the most common configurations of the features are provided in terms of profiles, which also can be selected in the endpoint. A default profile will always be applied if no profile or feature is selected explicitly. In most cases, consumers don't 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 page control with the following query parameter:

Paging over the whole resource

Example

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

Integration Patterns

CDQ recommends different patterns to integrate with our SOAP or REST APIs:

• Transactional: Process requests one by one.
• Bulk: Parallelize processing by sending many requests into one. Bulk endpoints parallelize workload and optimize performance. Please note that different rate limits occur for bulk endpoints.
• Data Mirror: Use continuously running monitors to process your data and distribute workloads.
• Analytical: Dump analytical data and process on your own.

Use the following table to pick the proper integration pattern for your use case, depending on the data volume and/or expected throughput.

Values characters limit

The length of the single value in the request is limited to 1024 characters.

Rate Limits

Rate limits help prevent short-term abuse and denial-of-service attacks and ensure the API remains available for all customers. CDQ limits the number of REST API requests you can make within a specific time.

Rate Limits are tracked on a workspace, user, or individual API Key level.

The following rate limits apply to all endpoints:

For selected endpoints, we have additional limits:

• Bulks: CDQ only allows one bulk of a type (i.e., Lookup or Fetch) to be processed sequentially. Remember that parallelization is applied on the server side, and parallelization on the client side is not required.

Quotas

Quotas control API utilization according to each customer's selected subscription. They help plan resources accordingly to ensure CDQ can meet service levels.

Please reach out to us if you need to adjust quotas.

The following default quotas are set as part of your subscription:

CDQ also defines quotas for access to external data sources:

Firewall ports

For secure communication, the following ports are required for the CDQ Cloud Platform:

Request Size Limiting

Payload size

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

Exceptions from this limit are gathered in the table below:

Upload file size

The same Request Size Limit applies to uploading the file.

• For uploading files <= 10 MB read File Upload instruction.
• For uploading files > 10 MB read Request Upload instruction.

Schema

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

TLS Certificates

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

Currently active

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

Certificate Details

The details of the certificates are as follows:

• • according to SSL Labs scoring

• • according to SSL Labs scoring

RSA Certificates

We provide the RSA certificates below for customers who don't support elliptic curve algorithms in their systems.

History

Versioning

Understanding version numbers

A version number uniquely identifies each API or App release. The structure of the version follows the standards of Semantic Versioning 2.0.

Format and example:

<MAJOR>.<MINOR>.0+<BUILD TAG>
25     .45     .0+202007747438

• Major: Incremented when incompatible API changes are releases
• Minor: Incremented when capability or fixes are released in a backwards-compatible manner
• Build: Timestamp of the build

Each API or App has its release cycle and thus, its 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

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

https://api.cdq.com/reference-data/rest/businesspartners/lookup
https://api.cdq.com/reference-data/rest/businesspartners/v2/lookup

Tags

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

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

Version selector by tags

End-of-life

Beta Versions

Beta versions are introduced to provide developers with early access to the capability and features of the API before its full release. This allows developers to test the API in real-world scenarios, provide feedback, and suggest improvements. Beta versions help to identify and address any issues or bugs or refine documentation. Additionally, beta testing enables developers to integrate the API into their applications and services, allowing for smoother adoption and transition once the API is officially launched.

API Beta Versions

Version selector with beta flag

Endpoint Beta Versions

Parameters, properties and toggle features Beta Versions

Implementation

The following guidelines support developers in building rocket-solid client implementations.

Authorization

A1: Token Management Always uses the latest token for authorization. Tokens are valid for a limited time and must be refreshed before expiration.

{
    "access_token": "eyJhbG...HSmgnS_0",
    "expires_in": 1800,
    "token_type": "Bearer"
}

Schema

S1: Safe consumption of API responses. Be aware that in the API response, 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 something similar.

{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  "lastPaymentDate" : "2021-18-45"
  "country" : "DE"
  ..
}

{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  // ATTENTION: field "lastPaymentDate" is null so it will not be part of the response
  "country" : "DE"
  ..
}

S2: Safe consumption of enums Enumerations provide a fixed set of values for specific fields. Adding additional enum values is considered a non-breaking change. Your client implementation should be able to handle unknown enum values gracefully.

According to the official documentation, "If the server adds new enum cases unknown by an old spec/client, the client will fail to parse the network response. With this option enabled, each enum will have a new case, 'unknown_default_open_api', so that when the server sends an enum case unknown by the client/spec, they can safely fall back to it."

Specifications

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