API design guidelines

API

API is an acronym for Application Programming Interface. An API is a standard non-graphical interface that makes an application’s functionality available to other applications over a network. The two databases connected by an API can share data based on predefined permissions. API work like digital building blocks, datas retrieved allow you to build bespoke risk management process within your own connected application.

JOBID

Our Job API allows to manage the asynchroneous mode of our Post/Patch/Delete calls. Please pick the jobId provided in the response and call our job API endpoint, and keep polling until its status turns from 'pending' into 'processed'. Click on the ressourceUrl provided under 'processed' and get the coverStatus of your request.

 

WEBHOOK

An alternative for 'polling jobs' is to integrate our webhook feature to be informed when you job has been processed. 

Two steps are necessary:

 

1) In Headers of your Post call, please leave your callback URL and timeToLive. This endpoint must be in HTTPS, and this object is stringified and base 64 encoded.

{​​​
  "callbackUrl": "https://client_url.com/Webhook",
  "timeToLive": 24
}​​​​

Example: {​​"https://btsapi-uat.flore-logistics.com/v1/api/ehtest/testing/HFPRIX/testPost", "timeToLive": 24}​​​

2) Our expert team whitelists your domain.

 

Pagination

Any resource that could return a large, potentially unbounded list of resources in its GET response implements pagination using the patterns described here.

Sample URI path: /accounts?pageSize={pageSize}&page={page}

Clients MUST assume no inherent ordering of results unless a default sort order has been specified for this collection.

 

Pagination in a GET Context: Query Parameters

• pageSize: A non-negative, non-zero integer indicating the maximum number of results to return at one time. This parameter:
  • optional for the client to provide.
  • has a default value, when the client does not provide a value, defined by the API provider. If no value is specified, the default value for pageSize is equal to 20.
  • If the pageSize is higher than the number of results, the API will return an HTTP status 200 and the real number of results in the header response parameter Total-Items if the totalRequired is set to true.
  • If the pageSize is higher than the default value, the default value is used instead.
  • If the pageSize is negative or null, a 400 Bad request error is returned.
• page: A non-negative, non-zero integer representing the page of the results. This parameter:
  • Optional
  • Has a default value of 1 for when the client does not provide a value.
  • If the page parameter is negative or null, the default value equal to 1 is used instead.
  • If a page number is too large - for instance, if there are only 50 results, but the client requests pageSize=100&page=3 - the resource responds with the HTTP status code 200 OK and an empty result list.
• totalRequired: A boolean indicating total number of items (Total-Items) and pages (Total-Pages) are returned in the response. This parameter:
  • is optional
  • has a default value of false.
  • may be used by the client in the very first request. The client may then cache the values returned in the response to help build subsequent requests.
  • is only implemented when it improves API performance and/or is necessary for front-end pagination display

 

Pagination in a POST context

The request object used in the POST body has to contain a new attribute named "pagination" of type object Pagination defined as following

Response Properties

The response body contains an array of the expected objects. The response is common to the GET and POST context.

The response header should contain (Unless there are performance or implementation limitations) 3 parameters 

• Total-Items is used to indicate the total number of items in the full result list, not just this page.
  • If totalRequired has been implemented by an API, then the value is only returned when totalRequired is set to true.
  • If totalRequired has not been implemented by an API, then the value may be returned in every response if necessary, useful, and performant.
  • If present, this parameter is a non-negative integer.
  • Clients must not assume that the value of Total-Items is constant. The value MAY change from one request to the next.
• Total-Pages is used to indicate how many pages are available, in total.
  • If totalRequired has been implemented by an API, then the value will only be returned when totalRequired is set to true.
  • If totalRequired has not been implemented by an API, then the value may be returned in every response if necessary, useful, and performant.
  • If present, this parameter is a non-negative, non-zero integer.
  • Clients must not assume that the value of Total-Pages is constant. The value may change from one request to the next.

• Links can be an array containing one or more HATEOAS link relations that are relevant for traversing the result list.

Page Navigation

 

Relationship	Description
self	Refers to the current page of the result list.
first	Refers to the first page of the result list. If you are using pageToken, you may not return this link.
last	Refers to the last page of the result list. Returning of this link is optional. You need to return this link only if totalRequired is specified as a query parameter. If you are using pageToken, you may not return this link.
next	Refers to the next page of the result list.
prev	Refers to the previous page of the result list.

 

Sorting

Results could be ordered according to sorting related instructions given by the client. This includes sorting by one (or more if you want to have a secondary, tertiary, … filter) specific field's value and sorting order (ascending or descending).

They are two cases, either we are in a context of a search using a GET or a more complex search using a POST

Sorting in a GET context

The “sort” parameter contains a list of couples keys (the field name), values (asc, dsc) separated by a “,”. The key and the values are separated by a “|” : {fieldName}|{asc|dsc},{fieldName}|{asc|dsc}

For instance: /accounts?sort=birthDate|asc,zipCode|dsc.

 

Sorting in a POST context

Your request object used in the POST body has to contain a new attribute named "sort" (or "sorts" if there are more than one sorting criterion) of type object Sort.

 

 

Common context

If the field name doesn't match with any attributes in the list of the returned business objects, it is ignored.

If the sorting value is not equal to asc or dsc, the default value asc is used