5.3.8.3 GET LicenseList

5.3.8.3.1    Purpose

This command can be used by a (prospective) Licensee to request a list of licenses (and licence revocations) from a (prospective) Licensor.

The (prospective) Licensee will call, after appropriate authentication if needed, the Web Service address previously agreed between a (prospective) Licensee and a (prospective) Licensor.

5.3.8.3.2    Parameters

In order to allow the Web Service caller to request a specific list of items to be returned in response to this call, the web server shall support the following query syntax defined in RfC 3986. It is permissible to communicate multiple queries separated by ampersands (&). If multiple queries are provided they shall be deemed to be logically AND-combined.

  1. from: Get items older than this time stamp (inclusive):

    1. The time stamp shall be provided in ISO 8601 format (yyyy-mm-dd);

  2. to: Get items newer than this time stamp (inclusive):

    1. The time stamp shall be provided in 8601 format (yyyy-mm-dd);

  3. offset: Offset into list of the first item to return; and

  4. limit: Maximum number of items to return:

    1. If the limit is set to 0 it means "all" items.

The example below requests an Atom feed containing 10 entries starting from the 100th item generated in January 2016:

 

GET https://www.example.com/base/url?from=2016-01-01&to=2016-01-31&offset=100&limit=10

 

Other query formats may be used on bilateral agreement between a (prospective) Licensee and a (prospective) Licensor.

The  GET LicenseList command may also be used without any parameters. In that case the web server will decide the items to send in the Atom feed.  

5.3.8.3.3    Syntax of Reply

The web server shall return one of the following standard HTTP status codes with their standard HTTP response code semantics:

  • 200 (OK);

  • 400 (Bad request);

  • 401 (Unauthorised);

  • 404 (Not found);

  •  406 (Not Acceptable query);

  • 414 (Request-URI Too Long);

  • 503 (Service unavailable due to a temporary overloading or maintenance of the server); and

  • 500 (Internal server error)

Other standard HTTP status codes may be used on bilateral agreement between a (prospective) Licensee and a (prospective) Licensor.

The web server shall also return to the calling Web Service client an Atom feed document that meets any parameters (if provided) as defined elsewhere in this standard.