CDL API

From CDL
Jump to: navigation, search
Managed element
Last edit 19 November 2018 14:22:40
Support contact 
A member of the CDL Team who is responsible for a specific element of the CDL infrastructure.
Martin Ofner

From an integration perspective, CDL web services are the most important component of the CDL infrastructure. They provide the technical link between your business applications and the CDL cloud services. We follow the REST design principle for web services which allows for lightweight interface design and easy integration. Of course, all web services are also available at WSDL interfaces.

Specification

The CDL web services implementation follows the REST architectural style and are implemented on the basis of the JAX-RS specification. Of course, all services are also available at WSDL interfaces.

For easy development, discovery, and integration visit our CDL web service documentation. The documentation follows the Swagger specification, an accepted standard for describing RESTful APIs.

Human readable an technical specifications are provided at the following URIs:

Schema

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format.

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:

  • 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.
  • 403 (Forbidden): The requester is not allowed to access the requested resource (e.g. if the requester is not subscribed to the requested business partner).
  • 404 (Not Found): The requested resource (e.g. a business partner) was not found.
  • 405 (Method Not Allowed): A request was made of a resource using a request method not supported by that resource (e.g. using GET on a service which requires data to be presented via POST).
  • 406 (Not Acceptable): Provided data (e.g. a created or updated business partner) violates business rules. Violated business rules are reported by the response entity.
  • 409 (Conflict): For provided data (e.g. a created or updated business partner) matching resources were found in the CDL database. Matching resources and matching information are provided by the response entity.
  • 415 (Unsupported Media Type): The request entity has a media type which the server or resource does not support.
  • 500 (Internal Server Error): An unexpected error occurred during request processing. This should not happen and should be reported to the CDL software team.

All error objects have a HTTP status code and a detailed message so that your client can tell what the problem is.

{
   "statusCode": "404",
   "message": "There is no business partner with the requested CDL-ID",
}

Pagination

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

Authentication

All web method calls require authentication. Credentials (i.e. username and password) have to be submitted in the HTTP header using basic authentication. Information security is ensured by the TLS protocol and, hence, encrypted communication via HTTPS. Our TLS certificates will be downloaded by all current web browsers when you visit our websites. Or you can download the certificates here.

In order to let you connect in a secure manner to our infrastructure, we're using high-grade and latest technology TLS certificates issued by SwissSign AG.

TLS Certificates

Certificate Chain

When connecting to our services, it may be necessary for some particular clients to explicitly download and import SwissSign's appropriate intermediate certificate. The following listing links to the official certificate download pages hosted by SwissSign, where you are able to download the appropriate certificates in all common filetypes:

Download CDL certificate

The certificate for https://www.corporate-data-league.ch is provided in this section for your convenience

JSON format

Beside XML, you can also use JSON messages to communicate with CDL cloud services. The following listing shows an example response of the address cleansing service.

{
  "addressString":"Lukasstrasse 4, 9008 Saint Gallen, Switzerland",
  "administrativeArea":{
    "value":"Sankt Gallen",
    "subAdministrativeArea":{
      "value":"Sankt Gallen"
    }
  },
  "country":"Switzerland",
  "latitude":47.4394863,
  "locality":{
    "value":"Saint Gallen",
    "subLocalities":[
      {
        
      }
    ]
  },
  "longitude":9.3951915,
  "postCode":{
    "value":"9008"
  },
  "premise":{
    
  },
  "thoroughfare":{
    "value":"Lukasstrasse 4",
    "type":"Street",
    "number":"4"
  }
}

To force a JSON response to a service call, you have to include an Accept header into the HTTP request with application/json value.