Download OpenAPI specification:Download
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.
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.0 | None |
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" |
This endpoint returns all the available plugins that can be used to make requests to carrier specific schedule endpoints (such as POST /schedule
)
Authorizations: |
type required | Array of string Items Enum:"AIR" "FCL" "LCL" The products which matching plugins you wish to retrieve |
List of available plugins
Provide at least one valid 'type' parameter
Credentials not provided, signature expired, or error decoding
Access not granted through permissions
Request throttled, too many requests
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: |
mode required | string Enum:"sync" "async" Whether to wait for the result or retrieve it later |
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> |
Synchronous request response including schedule
Asynchronous request response
Credentials not provided, signature expired, or error decoding
Access not granted through permissions
Request throttled, too many requests
The request timed out, we recommend you call with parameter type=async
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: |
request_id required | string <uuid4> The ID provided in the request body |
Schedule result for the provided request ID
Credentials not provided, signature expired, or error decoding
Access not granted through permissions
Not Found
Request throttled, too many requests
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: |
origin required | string <unlocode> |
destination required | string <unlocode> |
scope required | object |
date_from required | string <date-time> |
date_until required | string <date-time> |
Asynchronous request response
Credentials not provided, signature expired, or error decoding
Access not granted through permissions
Request throttled, too many requests
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: |
request_id required | string <uuid4> The ID provided in the request body |
Schedule result for the provided request ID
Credentials not provided, signature expired, or error decoding
Access not granted through permissions
Not Found
Request throttled, too many requests