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 routes 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"    }  }}

You'll soon find under the Protocol/V5 Specific section a description of all principle set up with this new V5 version.

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, route paths, request parameters or bodies, expected response body schemas) and provides useful samples.

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

You can learn more about this API specification 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 :