QwykInvenio Schedules API (1.1)

Download OpenAPI specification:Download

E-mail: api.support@qwyk.io

About

The Schedules API is an HTTP API served by the Invenio gateway providing endpoints to interact with schedules, making requests (either synchronously or asynchronosly) and retrieving results for earlier made requests. Invenio is built on a broker pattern where a request are received by the gateway, and passed to the broker which then dispatches one or more tasks to one or more workers. This means it is generally advised or required to retrieve the results through repeated polling rather than synchronously waiting for the response.

Security

CORS (Cross-Origin Resource Sharing)

This API includes Cross-Origin protection to guard against abuse. In order to whitelist any applications that require CORS Headers to be present on the response, please make a request to api.support@qwyk.io mentioning the hosts that need to be whitelisted and a brief description of your implementation. (localhost and localhost:0-99999 are whitelisted by default)

Access-Control-Allow-Headers

Our CORS configuration allows the following HTTP headers. Should you need to make requests with additional headers, please mention them in your whitelist request.

  • 'accept',
  • 'accept-encoding',
  • 'authorization',
  • 'content-type',
  • 'dnt',
  • 'origin',
  • 'user-agent',
  • 'x-csrftoken',
  • 'x-requested-with',
  • 'x-csrf-token'

Versioning

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer Invenio daemons.

This documentation is for version 1.0 of the API. Use this table to find documentation for previous versions of the API:

API Version Changes
Latest None
1.1 Added 'schema' query on MultiSchedules
1.0 None

Authentication

JSONWebToken

Authentication credentials need to be passed as a JWT token in the Authorization header for all requests. The API for obtaining JWT tokens using your credentials can be found here: Invenio Authentication API

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT token"

Plugins

Find available carrier plugins to make requests against

Get product plugins

This endpoint returns all the available plugins that can be used to make requests to carrier specific schedule endpoints (such as POST /schedule)

Authorizations:
query Parameters
type
required
Array of string
Items Enum:"AIR" "FCL" "LCL"

The products which matching plugins you wish to retrieve

Responses

200

List of available plugins

400

Provide at least one valid 'type' parameter

401

Credentials not provided, signature expired, or error decoding

403

Access not granted through permissions

429

Request throttled, too many requests

get /plugins
EU1 Production Gateway
https://eu1-gateway.invenio.qwyk.io/schedules/v1/plugins

Response samples

application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Schedule

Obtain a single carrier schedule

Send a schedule request

This method allows for the synchronous or asynchronous (using the mode query parameter) retrieval of a carrier's schedule. Making this request, a process will be started on the server that collects the schedules. When running the process synchronously, your request will wait until the job has completed or until it times out (usually after 60 seconds.) When running the request asynchronously (recommended) you may retrieve the status and results using the /schedule/{request_id} endpoint (the request_id being the value provided in the 202 result body of this request.) When the status field in the returned body contains the value PENDING, the job has not yet completed and no results are available. When the value for the status field is COMPLETED or FAILED the final result is available and no further updates to the set are to be expected.

Note that the cached resultset will expire after 300 seconds so your call must be made within this timeframe.

Authorizations:
query Parameters
mode
required
string
Enum:"sync" "async"

Whether to wait for the result or retrieve it later

Request Body schema: application/json
origin
required
string <unlocode>
destination
required
string <unlocode>
carrier_hash
required
string <md5>
date_from
required
string <date-time>
date_until
required
string <date-time>

Responses

200

Synchronous request response including schedule

202

Asynchronous request response

401

Credentials not provided, signature expired, or error decoding

403

Access not granted through permissions

429

Request throttled, too many requests

504

The request timed out, we recommend you call with parameter type=async

post /schedule
EU1 Production Gateway
https://eu1-gateway.invenio.qwyk.io/schedules/v1/schedule

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "origin": "string",
  • "destination": "string",
  • "carrier_hash": "string",
  • "date_from": "2018-06-17T12:49:07Z",
  • "date_until": "2018-06-17T12:49:07Z"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "request_id": "string",
  • "status": "PENDING",
  • "request":
    {
    },
  • "results":
    [
    ]
}

Get async schedule result

Use this method to retrieve the results of an earlier made asynchronous request. When the status field in the returned body contains the value PENDING, the job has not yet completed and no results are available. When the value for the status field is COMPLETED or FAILED the final result is available and no further updates to the set are to be expected. You may call this method multiple times to retrieve its state, but note the requests get throttled. Observe the response headers to retrieve the throttle state.

Authorizations:
path Parameters
request_id
required
string <uuid4>

The ID provided in the request body

Responses

200

Schedule result for the provided request ID

401

Credentials not provided, signature expired, or error decoding

403

Access not granted through permissions

404

Not Found

429

Request throttled, too many requests

get /schedule/{request_id}
EU1 Production Gateway
https://eu1-gateway.invenio.qwyk.io/schedules/v1/schedule/{request_id}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "request_id": "string",
  • "status": "PENDING",
  • "request":
    {
    },
  • "results":
    [
    ]
}

MultiSchedules

Obtain a parsed schedule batch for one or more distinct carriers or one or more products. When using products, the engine will query all the active providers for the requested products and return those results.

Send a multischedules request

This method allows for the asynchronous retrieval of a parsed schedule set. Making this request, a process will be started on the server that collects the schedules and parses them to the schema. At any time you may retrieve the intermediate results using the /schedules/{request_id} endpoint (the request_id being the value provided in the 202 result body of this request.) When the status field in the returned body contains the value PENDING, intermediate results will be provided. When the value for the status field is COMPLETED or FAILED the final result is available and no further updates to the set are to be expected.

Note that the cached resultset will expire after 300 seconds so your call must be made within this timeframe.

Authorizations:
query Parameters
schema
string
Default: "simple"
Enum:"simple" "extended"

With simple (default) a simple results set will be provided, with extended the results will be parsed and include lists of carriers, routes, and locations. The extended schema adds about 900ms of overhead on PENDING result responses and the first completed response.

Request Body schema: application/json
origin
required
string <unlocode>
destination
required
string <unlocode>
scope
required
object
date_from
required
string <date-time>
date_until
required
string <date-time>

Responses

202

Asynchronous request response

401

Credentials not provided, signature expired, or error decoding

403

Access not granted through permissions

429

Request throttled, too many requests

post /schedules
EU1 Production Gateway
https://eu1-gateway.invenio.qwyk.io/schedules/v1/schedules

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "origin": "string",
  • "destination": "string",
  • "scope":
    {
    },
  • "date_from": "2018-06-17T12:49:07Z",
  • "date_until": "2018-06-17T12:49:07Z"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "request_id": "string",
  • "status": "PENDING",
  • "request":
    {
    },
  • "results":
    [
    ],
  • "carriers":
    [
    ],
  • "routes":
    [
    ],
  • "locations":
    [
    ]
}

Get async schedules result

Use this method to retrieve the (intermediate) results of an earlier made request. When the status field in the returned body contains the value PENDING, intermediate results will be provided. When the value for the status field is COMPLETED or FAILED the final result is available and no further updates to the set are to be expected. When the job has not yet completed raw data will be parsed on request which may cause some additional latency, as the chained job becomes completed the parsed resuls will be served directly. You may call this method multiple times to provide partial result sets in your client, but note the requests get throttled. Observe the response headers to retrieve the throttle state.

Authorizations:
path Parameters
request_id
required
string <uuid4>

The ID provided in the request body

Responses

200

Schedule result for the provided request ID

401

Credentials not provided, signature expired, or error decoding

403

Access not granted through permissions

404

Not Found

429

Request throttled, too many requests

get /schedules/{request_id}
EU1 Production Gateway
https://eu1-gateway.invenio.qwyk.io/schedules/v1/schedules/{request_id}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "request_id": "string",
  • "status": "PENDING",
  • "request":
    {
    },
  • "results":
    [
    ],
  • "carriers":
    [
    ],
  • "routes":
    [
    ],
  • "locations":
    [
    ]
}