Requests

How to make API requests

Making an API request

An API request consist of:

  • HTTP method: GET, POST, PUT or DELETE

  • HTTP headers: authorization and content type

  • URL: HTTPS, environment, service, method and parameters

  • JSON body which contains the payload

HTTP method

The API supports

  • GET to get a specific JSON object, like a purchase order, or to download a document (one JSON object or document is returned) or to query objects (a JSON collection is returned)

  • POST to create a new JSON object or upload a document

  • PUT to update an existing JSON object

  • DELETE to delete an existing JSON object or document

HTTP headers

Authorization

Use the Authorization header for basic authentication and token authorization, see Authentication

Content-Type

Use the Content-Type: application/json header in case of POST or PUT with a JSON body.

Use the Content-Type: application/xml header in case of PUT with an XML body.

URL

The API uses the REST software architectural style that defines a set of constraints to be used for creating Web services. The API additionally uses a command and query style.

An URL is build up like this: https://environment/service/method/parameters?parameters

HTTPS scheme

The API only supports HTTPS, see Encryption.

Environments

Tradecloud has three environments:

Services

Each environment has a set of services which you can find on each environment page, like the acceptance test environment and production environment

On the environment page for each service the API endpoint you can find the OpenAPI 2.0 Specification YAML file, the OpenAPI UI rendering, the health and label (version) is published.

Common used services are:

  • authentication for authentication, to get a token

  • api-connector for buyer and supplier ERP integration

  • object-storage to upload and download documents

  • order for order/line commands

  • order-search for order queries

  • order-line-search for order-line queries

  • sci-connector for buyer ERP integration using SCSN

Methods

In each OpenAPI 2.0 Specification you can find the methods supported by the service. For example the api-connector service:

POST /api-connector/order sends an order by the buyer

POST /api-connector/order-response sends an order response by the supplier

Parameters

Most service methods have either path parameters, query parameters and/or a JSON body or XML body

Path parameters

A request can have a path parameter such as an {id} in object-storage service download method:

GET /object-storage/download/{id}

Query parameters

A GET request can have a query parameter such as a query in company-search:

GET /company-search?query=name

JSON body

A POST request has a JSON body (payload), such as a purchase order sent to the api-connector service order method:

POST /api-connector/order

{
"order": {
"companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supplierAccountNumber": "12345",
"purchaseOrderNumber": "PO123456789",
"destination": {
...

JSON is a standard published as RFC 8259 and ECMA-404 (PDF)

XML body

A request can have an XML body, such as purchase order sent to the sci-connector service order method:

PUT /sci-connector/order

<?xml version="1.0" encoding="UTF-8"?>
<Order>
<ID>123</ID>
<IssueDate>2018-10-06</IssueDate>
<Note>[Free-form text]</Note>
<BuyerCustomerParty>
...

Tradecloud supports XML following the SCSN Standard