Skip to content

LCP Status Server API

Jump to bottom
L. Le Meur edited this page Sep 16, 2020 · 4 revisions

In brief

The License status server stores, for each license, a its ID, its status, the date of last update of the license rights (in the case of a loan return or extension), the date of last update of the status, plus a sequence of past events. Each event is made of an event type, timestamp, originating device identifier and name.

The License Status server exposes several REST API methods:

Public methods (accessible from the web)

  • Return a license status document
  • Process a device registration
  • Process a lending return
  • Process a lending renewal

Private methods (authentication required)

  • Create a license status document
  • Filter licenses
  • List all registered devices for a given licence
  • Revoke/cancel a license

From the user device, the registration workflow is as follows:

  1. The user makes a transaction;
  2. He gets a license;
  3. Each time he opens the publication, if the license contains a link to a status document and the device is online, then the status document is requested;
  4. If the device wasn’t registered before for this license and if the status document contains an registration link, then the device calls the registration link;
  5. As per the specification, if the server rejected the registration, the device must not let the user open the book before a successful attempt is made. It should store a positive result;
  6. If the license was updated (test of a timestamp in the status document), the device downloads the updated license.

API

Notify of a new license

Private method.

This method is called by the License Server after generation of a license. The complete license is provided as a payload; the Status Server then extracts the information it needs from the license structure.

PUT <LSDbaseURL>/licenses

Payload: {license} (json).

Return:

  • 201: created
  • 400 (bad request) The license structure is malformed.
  • 5xx: internal error

Return a license status document

The method generates and returns a license status document, using a license identifier as key.

GET <LSDbaseURL>/licenses/<license_id>/status

Return:

Process a device registration

Activate a device for a given license.

Any certified device MUST call this method the first time it processes an LCP license, and SHOULD store a positive answer.

POST <LSDbaseURL>/licenses/<license_id>/register{?id, name}

where:

  • id is the device identifier in the form of a UUID
  • name is the device name in the form of a URL-encoded string

Return:

  • 200+ the updated license status: ok
  • 400 (bad request) Your device could not be registered properly
  • Probable causes:
  • The license has been revoked
  • The identifier is badly formatted
  • The name is too long
  • 404 (not found) This license does not exist in the database (type http://readium.org/license-status-document/error/notfound)
  • 5xx (internal error) An unexpected error has occurred.

Process a lending return

The method checks that the calling device is activated, then modifies the end date associated with the given license; it will be set to “now”. This method calls the “rights” method of the LCP server.

PUT <LSDbaseURL>/licenses/<license_id>/return{?id, name}

where:

  • id is the device identifier in the form of a UUID
  • name is the device name in the form of a URL-encoded string

Return:

  • 200 + the updated license status: ok
  • 400 (bad request) Your publication could not be returned properly.
  • 403 (rejected) Your publication has already been returned before.
  • 403 (rejected) Your publication has already expired.
  • 404 (not found) This license does not exist in the database.
  • 5xx (internal error) An unexpected error has occurred.

Process a lending renewal

The method checks that the calling device is activated, then modifies the end date associated with the license.This method call the “rights” method of the LCP server.

PUT <LSDbaseURL>/licenses/<license_id>/renew{?end, id, name}

where:

  • end is the requested end date and time, in the form of a W3C date-time (YYYY-MM-DDThh:mm:ssTZD)
  • id is the device identifier in the form of a UUID
  • name is the device name in the form of a URL-encoded string

Return:

  • 200+ the updated license status: ok
  • 400 (bad request) Your publication could not be renewed properly.
  • 403 (rejected) Incorrect renewal period, your publication could not be renewed.
  • 404 (not found) This license does not exist in the database.
  • 5xx (internal error) An unexpected error has occurred.

Note 1: in the absence of the end parameter in the request, the default number of additional days (renew_days) found in the configuration file will be used. In there is none, an internal error is sent back with a message “No default renew period (parameter renew-days) found in the configuration file.”.

Note 2: the potential rights end parameter is initialized at the time the license is added to the LSD server. The corresponding number of days is the max value between a/ the value of renting_days in the configuration file and b/ the number of days passed as the "end" parameter of the method. If means that if renting_days is lower than end, no renewal is possible (potential_rights_end equals the initial end of the loan).

Check overshared licenses

Private method.

This method returns a sequence of license statuses, in their id order.

GET <LSDbaseURL>/licenses{?devices, page, per_page}

It is used to filter the licenses that have been used by a large number of devices. The devices parameter represents the minimum number of devices.

The pagination mechanism is based on the Link headers RFC (https://tools.ietf.org/html/rfc5988 ) and the Github pagination syntax (https://developer.github.com/v3/#pagination).

Partial license statuses are returned, e.g.:

{
  "id": "234-5435-3453-345354",
  "status": "active",
  "message": "Your license is currently active and has been used on at least one device.",
  "updated": {
    "license": "2014-08-05T00:00:00Z",
    "status": "2014-08-08T00:00:00Z"
  },
  "device_count": "100"
 }

Return:

  • 200 + the requested array of partial licenses: ok
  • 401: unauthorized
  • 400: bad request; the devices boundary or pagination parameters are wrong
  • 5xx: internal error

Example: http://lsdserver.my.org/licenses?devices=100&page=2

List all registered devices for a given license

Private method.

Gives data to the provider (and publisher) about the use of a given license.

GET <LSDbaseURL>/licenses/<license_id>/registered

Return:

Revoke/cancel a license

Private method.

This methods revokes (after use) or cancels (before use) a license by sending a partial license status document, containing the new status and a message indicating why the status is being changed.

PATCH <LSDbaseURL>/licenses/<license_id>/status

A 'cancel' command returns a 400 error if the current status is not 'ready' and 'revoke' returns an error if the current status is not 'active'.

The LSD server internally calls the LCP server and updates the expiration time to “now”.

Payload: {license-status} (json)

Return:

Sample partial license status document:

{
  "status": "revoked",
  "message": "Your license has been revoked because it has been used on 589 devices in less than a week.",
}
Clone this wiki locally