Skip to main content

Using Warehouse as an ACS Provider

While the De Marque warehouse can manage a variety of fulfillment methods as well offer various options for license management, it can also be used as simpler mechanism to obtain time-limited ACSM files.

In order to do that, content must first be uploaded to the platform (in order for us to encrypt the content) and licenses need to be associated to each content piece.

When an ACSM is needed, it can be obtained through the checkout mechanism described further.

API Considerations​

API Format​

The De Marque Warehouse solution offers various APIs based on the GraphQL standard, allowing clients to fetch and update only the required information

The GraphQL API can be reached at https://api.demarque.dev/graphql

Introspection is available and can be used to read through the documentation.

Authentication​

Authentication is made through the Authentication header, using a Bearer token. The token you were provided with can be used directly in the API.

Preparing the content​

Getting access to a namespace​

The De Marque support team will grant you access to one or more organizational units called namespaces, which can be used to separate the various contents and licenses you wish to offer. Namespaces both have a user-understandable identifier (e.g. my-first-namespace) as well as an UUID used through the APIs (e.g. 45a6a8e3-af9b-4c40-bcf5-e22a1718c67c).

Uploading the content​

Through the API​

You can create publications and thus upload content using specialized guide: Creating a publication

Through an SFTP transfer​

Your individual user credentials will have access to a SFTP at incoming.demarque.dev. In there, you will find automatically generated folders for each of the namespaces you have access to. You can upload content there and it will automatically be processed, based on the name of the files.

EPUBs and PDFs should be named {ISBN}.epub and {ISBN}.pdf respectively That ISBN will be used to create the primary identification key for the content, it will also be reflected as the isbn field in the API.

Adding metadata (optional)​

There are many ways in which you can associate metadata to each publication.

  • Using ONIX over SFTP
  • Using the API directly (See Creating a publication)
  • Using the interface (with the form or with an Excel file)

Creating the licences​

While the De Marque APIs can help enforcing lending rules (concurrency, number of tokens, expiration), if all you want is to provide ACSM files, you can create unlimited licences where no constraints will be applied.

You can do that using the interface, or with the API.

If you created the publication using the SFTP, you might not have its internal ID. To resolve the ID from the ISBN you gave it, you can do the following query:

query {
  publicationByISBN(isbn: "example-isbn", namespaceId: "your-namespace-id") {
    id
  }
}

Then you can apply a mutation to create the license:

mutation CreateLicense {
      createLicense(
        input: {
          entityId: "the-previously-retrieved-id"
          namespaceId: "your-namespace-id"
          source: "api"
          protection: { copy: 0, devices: 6, print: 0, tts: true }
          terms: {}
        }
      ) {
        id
      }
    }

Keep the resulting ID as it will be what allows you to perform checkouts.

At the time you need an ACSM file​

Create a new loan if needed​

The checkout flow uses another endpoint using a REST-style API, and thus a different server: https://fulfillment.demarque.dev

It still uses the same authentication mechanism from the GraphQL API

To checkout a loan, use the following API: POST /licenses/checkout?{id,checkout_id,expires,patron_id,notification_url}

The following parameters are used:

id: The previously-obtained id for the License, should be a full URI

checkout_id: A unique identifier provided by you to identify the loan, to avoid double-checkouts

expires: The ISO8601 timestamp at which the loan will expire

patron_id: An identifier of the patron, provided by you

notification_url: Optional. An URL at which you can receive a webhook about the loan expiring or being returned by the user.

What you will get back from that call, if successful, is a License Status Document. That file will give you the various ways to access the various ways a user can access the content and its schema is described here: https://readium.org/lcp-specs/releases/lsd/latest

Here's an edited example:

{
    "id": "https://warehouse.demarque.dev/loans/95ca5828-0e9b-4097-a4d0-cde20da44ec5",
    "status": "active",
    "updated": {
        "license": "2022-09-19T18:18:52.131Z",
        "status": "2022-09-19T18:18:52.131Z"
    },
    "links": [
        {
            "rel": "license",
            "href": "https://fulfillment.demarque.dev/loans/https%3A%2F%2Fwarehouse.demarque.dev%2Floans%2F95ca5828-0e9b-4097-a4d0-cde20da44ec5/acs4/license",
            "type": "application/vnd.adobe.adept+xml"
        },
        {
            "rel": "self",
            "href": "https://fulfillment.demarque.dev/loans/https%3A%2F%2Fwarehouse.demarque.dev%2Floans%2F95ca5828-0e9b-4097-a4d0-cde20da44ec5/status",
            "type": "application/vnd.readium.license.status.v1.0+json"
        },
    ],
    "potential_rights": {
        "end": "2022-10-01T00:00:00.000Z"
    }
}

Downloading the ACSM​

The license document is a JSON object containing in particular a series of links. To fetch the ACS4 variant of the file, you can find the link withe the following properties: its rel should be license, and its type should be application/vnd.adobe.adept+xml. That link is unauthenticated, and can be given directly to the end user or pre-fetched by your server to be handed to the client.

If you need to fetch the status document again, you can find its permanent URL using the link with a rel = "self"