CrossRef click-through service for Publishers

Adding your text and data mining Terms and Conditions to the click-through service

Publishers who require researchers to agree to a specific set of Terms and Conditions (T&Cs) before they are allowed to text and data mine content that they otherwise have access to (e.g. through an existing subscription) will need to make use of the click-through service.

The service performs four functions:

  • It allows publishers to upload and manage click-through text and data mining agreements for their content.
  • It allows researchers to browse, and accept/reject these text and data mining agreements
  • It provides each researcher with a secret Client API Token which they can use with their text and data mining tools to assert that they have accepted T&Cs relevant to the content that they are requesting via the CrossRef REST API.
  • It allows publishers to verify with the service that the owner of a specified Client API Token has accepted one or more relevant registered T&Cs.

Note that you must review and publish the T&Cs before researchers will be able to review and accept/reject them. But before you publish your T&Cs, be aware of the following constraints on managing the agreements:

  • T&Cs can only be edited and changed before they have been published.
  • Published T&Cs cannot be edited or deleted if one or more researchers have already accepted them.
  • Published T&Cs can be “disabled” in order to prevent new acceptances/rejections of that version of the agreement.

These limitations are designed to protect researchers from having the terms of a T&C agreement changed after they have accepted it.

Note the researchers face similar restrictions in that they cannot “reject” T&Cs that they have already “accepted”.

Registering a Publisher click-through agreement

Publishers can simply login to the click-through service using the same credentials that they use for depositing metadata with CrossRef.

Once logged- in, publishers can upload and mange their T&Cs. Every agreement registered must have:

  • A unique URI which points to a copy of the T&Cs on the publisher’s site
  • A unique name
  • A short, non-legalese description of the T&Cs
  • The full text of the T&Cs, in Markdown format

You can upload your T&Cs, safe drafts and publish online.

Remember that you must publish the T&Cs before researchers can preview, accept/reject them. But also note that, once a T&C agreement has been published and accepted by any researcher, it can no longer be edited or deleted. It can, however, be disabled, which prevents new acceptances/rejections of that version of the agreement.

Implementing the click-through service API

Every researcher who uses the click-through service to accept and/or reject T&Cs is issued with a secret Client API Token. Researchers will use this Client API token in their text and data mining tools for requesting the full text of an article. The publisher can then check with the click-through service API to see if the researcher associated with the secret token has accepted the T&Cs that are applicable to the full text they are seeking to download.

In order to query the Publisher API, each publisher is also assigned a Publisher API Token. Using the combination of these two tokens, the publisher can easily check to see which T&Cs have been accepted and/or rejected using a simple HTTP request. The publisher includes the Publisher Token in the headers of the request and the Client API token on the URI itself. The following curl command illustrates this.

curl -k  -H "CR-Clickthrough-Publisher-Token: MdvA59fGn8ukykYlSxJL6g" "https://apps.crossref.org/clickthrough/api/licenses/Ekcboi7Yb-D0RXnN-sqEuw" -D - -L

The response is a JSON structure that lists the publisher’s agreements that have been reviewed by the researcher with the given Client API Token.

{
  "result": "ok",
  "message": "licenses",
  "licenses": [
    {
      "uri": "http://www.crossref.org/tdm_license",
      "status": "accepted",
      "reviewed_at": "2013-07-02T14:52:06+00:00"
    },
    {
      "uri": "http://www.foo.bar",
      "status": "rejected",
      "reviewed_at": "2013-07-02T15:03:12+00:00"
    }
  ]
}

The publisher can then iterate through this result to see if the researcher had signed a relevant agreement for the content.

Please note two important things about the API:

  • The click-through service API requires the use of HTTPS. This is because both the Publisher API Token and the Client API Token need to be kept secret. They should never be passed on an open channel.
  • You should not check for T&Cs with every researcher request. Doing so will make your responses slow and overburden the click-through service API. It also isn’t necessary as a researcher cannot “reject” T&Cs that they have previously “accepted.” Rather, you should consider checking for a particular Client API token once every X requests or once every Y time span.

The following diagram summarises the interaction described above.

TDM Flow

Example Code

CrossRef has created an example publisher, Tinypub site that implements the CrossRef Metadata API, including rate limiting and IP-based subscription access. The code for the example code can be downloaded from Github for reference. Please note that this code is only meant to illustrate the workings of the  system. It is not in any way intended for production.