Queries

To ensure that one gets only most relevant results with reasonable performance, our API requests support filtering and pagination. Although specific endpoints can support only some part of described functionality, bellow we provide generic rules for making such requests.

• Authentication (HMAC)
• Pagination
• Sorting
• Search
• Errors

Authentication (HMAC)

Lighthouse API support a HMAC signature scheme for API authentication. You can find detailed instructions here.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

$ curl -X GET \
  'https://conecto-api.shift4payments.com/api/v1/export/244/tickets?filter[dateTimeFrom]=2018-03-01&filter[dateTimeTo]=2018-03-31' \
  -H 'Content-Type: application/json' \
  -H 'x-access-key: 3cac6f14875e1ed564e8e4f7c4b1916e' \
  -H 'x-signature: b8bc892d56050e4d929be06771222e32e42bc4d5679bb79e6fd3f61f20e15ff5' \
  -H 'x-timestamp: 1530194117'

Pagination

Pagination depends on Endpoint functionality

You can request results portion (page) using offset and limit query parameters.

Paginated results will display metadata information. Inside meta objects, there is count attribute of the total items matching current request.

{
  "meta": {
    "count": 27
  }
}

Sorting

Sorting depends on Endpoint functionality

Sorting is the process of arranging items in a certain sequence or order according to specific rules.

Requests that return a collection of items can be sorted providing sortBy query parameter. This query parameter can be passed as a JSON string, or URI encoded Object.

Available sorting rules:

For example, if you need to sort results by creation date from newest to oldest, the query JSON parameter will look like:

?sortBy={"createdAt":"DESC"}

or alternatively in URI-encoded form

?sortBy[createdAt]=DESC

Search

Search depends on Endpoint functionality

Requests that return a collection of items can be parametrised providing filter query parameter. This query parameter can be defined as a JSON string, or URI encoded Object.

For example, if you needed to filter a list that was created after 2007-03-01T23:59:59Z and before 2007-03-01T00:00:00Z the JSON query parameters would be:

?filter={"dateTimeFrom":"2007-03-01T00:00:00Z", "dateTimeTo":"2007-03-01T23:59:59Z"}

or alternatively in URI-encoded form

?filter[dateTimeFrom]=2007-03-01T00:00:00Z&filter[dateTimeTo]=2007-03-01T23:59:59Z

Errors

Lighthouse uses conventional HTTP response status to indicate the success or failure of an API request.

In general, status in the 2xx range indicates success, while codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Status in the 5xx range indicates an error with servers. 5xx errors are rare.

Common statuses

Error Response example

{
    "error": {
        "status": 400,
        "message": "name_is_required"
    }
}