V5: Call me HAL !

The aim of creating a new V5 version for our new and future APIs is to improve consistency and discoverability.
An API is easy to use when operations behave the same way for similar operations. Answers should be the same when responding to resource creation, resource filtering should provide the same capabilities for every resources etc.

More than just enforcing rules and behaviors, we try to set up a protocol that sticks to some kind of standard.
As there is no RFC to describe how a REST API should work, we made a choice that is widely spread over the REST API's world : HAL.

Hypermedia Application Language is a format that allows describing resources and links between resources by providing urls.

For example an etl resource should provide a link to retrieve its executions :

{
  "id": "123456",
  "name": "customer-daily-integration",
  "scheduling": {
    "frequency": "0 0 5 * * ?",
    "paused": false
  },
  "_links": {
    "self": "/v5/entities/MyEntity/etls/123456",
	"executions": "/v5/entities/MyEntity/etl-executions?etlId=123456"
  },
  "_audit": {
    "createdAt": "2019-11-20T12:00:00.000Z",
    "updatedAt": "2019-11-20T12:00:00.000Z"
  }
}

Retrieving a paginated list of etls should provide the links to navigate toward next or previous pages :

{
  "_embedded": {
    "etls": [
      {
        "id": "123456",
        "name": "customer-daily-integration",
        "scheduling": {
          "frequency": "0 0 5 * * ?",
          "paused": false
        },
        "_links": {
          "self": {
            "href": "/v5/entities/MyEntity/etls/123456",
		    "executions": "/v5/entities/MyEntity/etl-executions?etlId=123456"
          }
        }
      }
    ]
  },
  "filter": {},
  "page": {
    "pageNumber": 0,
    "pageSize": 1,
    "totalPages": 2,
    "totalElements": 2
  },
  "_links": {
    "self": {
      "href": "/v5/entities/MyEntity/etls"
    },
    "first": {
      "href": "/v5/entities/MyEntity/etls?page=0&pageSize=1"
    },
    "last": {
      "href": "/v5/entities/MyEntity/etls?page=1&pageSize=1"
    },
    "next":  {
      "href": "/v5/entities/MyEntity/etls?page=1&pageSize=1"
    }
  }
}

info

It is not planned to entirely phase out the V4 or replace it altogether with V5 operations. However, changes to single V4 operations can happen and will be announced through the process documented here.

OpenAPI

In order to help users to implement easily programs that make use of our APIs, we now provide for every V5 API an OpenAPI specification file that describes the protocol (urls, operation paths, request parameters or bodies, expected response body schemas) and provides usefull samples.

All of our V5 APIs specifications files are using OpenAPI 3.

You can learn more about this API specificiation format by reading OpenAPI Initiative's website.

Downloading OAS files

As OpenAPI community provides tooling for client generation in many programming languages, we allow you to download the OAS file for every V5 API :

OpenAPI​

OpenAPI