Entitlement API Specification – Integrators

Version: 1.0 (Dec 2019)

Audience: Integrators, consumers of the getFTR Entitlement API

Contributors: getFTR Technical Steering Group (TSG)

Document revision history

The Entitlement API establishes for a given document (DOI) and user affiliated institution (IDP EntityID) the entitled level of access and appropriate content links, whether that be to the Version of Record (VoR) or Best Available Version (BAV).

The Entitlement resource is the only resource declared on the Entitlement API.

Request

GET

/v1/entitlement?doi={doi}&entityID={entityID}

The full list of supported request parameters are described here:

Response

The Entitlement resource is returned in JSON form, refer to schema.

Entitlement object

Document object

The document object is returned in JSON form, refer to schema.

Entitlement truth table

The following truth table captures the legal combinations of VoR and BAV in the Entitlement resource:

#1 Version of Record (VoR)

Institution is entitled to the document. DOI and Institution are known and combined have entitlement rights. Response will contain a VoR (i.e. “vor” field).

Example:

Request

/v1/entitlement?doi=12.345/2018zz112233&entityID=https://example.idp.org&prettyPrint=true

Response

{
  "entitled": "yes",
  "doi": "12.345/2018zz112233",
  "entityID": "https://example.idp.org",
  "accessType": "open",
  "vor": [
    {
    "contentType": "application/pdf",
    "url": "https://example.publisher.com/doi/pdf/12.345/2018zz112233?entityID=https://example.idp.org"
    },
    {
    "contentType": "application/epub+zip",
    "url": "https://example.publisher.com/doi/epub/12.345/2018zz112233?entityID=https://idp.example.org"

    },
    {
    "contentType": "text/html",
    "url": "https://example.publisher.com/doi/full/12.345/2018zz112233?entityID=https://idp.example.org"

    }
    ],
  "document": "https://example.publisher.com/doi/abs/12.345/2018zz112233?entityID=https://idp.example.org"

}

#2 Best Available Version (BAV)

Institution is not entitled to the document. DOI and Institution are known and combined do not have entitlement rights. Response will be missing a VoR but a BAV is available (i.e. “bav” field). Example:

Request

/v1/entitlementdoi=12.345/2018zz445566&entityID=https://example.idp.org&prettyPrint=true

Response

{
  "entitled": "no",
  "doi": "12.345/2018zz445566",
  "entityID": "https://idp.example.org",
  "bav": [
  {
  "contentType": "application/pdf",
  "url": "https://example.publisher.com/doi/pdf/12.345/2018zz445566"
  }
],
"document":
"https://example.publisher.com/doi/abs/12.345/2018zz445566"
}

#3 No Best Available Version

Institution is not entitled to the document. DOI and Institution are known and combined do not have entitlement rights. Furthermore a BAV is not available. Example:

Request

/v1/entitlement?doi=12.345/2019zz778899&entityID=https://idp.example.org&prettyPrint=true

Response

{
  "entitled": "no",
  "doi": "12.345/2019zz778899",
  "entityID": "https://idp.example.org",
  "document": "https://example.publisher.com/doi/abs/12.345/2019zz778899"
}

#4 Maybe entitled

Institution/Department cannot be uniquely identified (additional SAML attributes required). The DOI is known. The scenario can arise in deferred authentication where only the entityID is supplied. A VoR is returned with a “maybe” entitled status.

Example:

Request

/v1/entitlementdoi=12.345/2018zz112233&entityID=https://example.idp.org&prettyPrint=true

Response

{
  "entitled": "maybe",
  "doi": "12.345/2018zz112233",
  "entityID": "https://example.idp.org",
  "accessType": "paid",
    "vor": [
    {
    "contentType": "application/pdf",
    "url": "https://example.publisher.com/doi/pdf/12.345/2018zz112233?entityID=https://example.idp.org"
    }
  ],
  "document": "https://example.publisher.com/doi/abs/12.345/2018zz112233?entityID=https://idp.example.org"
}

#5 Unknown Institution + Open/Free

DOI is known but the Institution is unknown (EntityID is missing or unknown). If the document is free or open-access a VoR is returned. Example:

Request

/v1/entitlement?doi=12.345/2018zz998877&prettyPrint=true

Response

{
  "entitled": "yes",
  "doi": "12.345/2018zz998877",
  "accessType": "open",
  "vor": [
    {
    "contentType": "application/pdf",
    "url": "https://example.publisher.com/doi/pdf/12.345/2018zz998877"
    }
],
  "document": "https://example.publisher.com/doi/abs/12.345/2018zz998877"
}

Transport (TLS)

All communications are encrypted over a TLS 1.2, or above, connection. The TLS handshake will exchange server certificates only.

Integrator ID

getFTR issues each Integrator with a unique “Integrator ID” String. Integrators present this identifier in every request as HTTP header “X-INTEGRATOR-ID”. getFTR will use this to lookup the “shared secret” (below).

Authentication (JWT)

Integrators must sign all API requests with a JWT bearer token ( rfc7519 ), which getFTR is responsible for verifying. getFTR issues each Integrator with a unique shared secret to sign requests.

getFTR issues each Integrator with a unique shared secret, a pseudo random generated
256 bit long number encoded in Base64 . This must be decoded into a raw byte array when
signing and verifying requests.

The following JWT properties, exhaustive list, have been adopted:

doi and idp are the only business property extensions to the JWT payload, deemed enough to confirm the authenticity of the Integrator and integrity of the request.

Integrators are responsible for generating valid Bearer tokens. Refer to Response Codes.

Example

Shared Secret:

RvayIrmfCUDyuHPBAb5yzpCPb5TKjJ7MSthgBAdMMdI

JWT Token Header

{
  "alg": "HS256",
  "typ": "JWT"
}

JWT Token Payload

{
  "iss": "mendeley",
  "aud": "getftr",
  "iat": 1568110518,
  "jti": "83d4f63a-6486-4653-ac0a-1bf3c82183af",
  "doi": "12.345/2018zz112233",
  "idp": "https://idp.example.org"
}

JWT Auth Header

Authorization: Bearer

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnZXRmdCIsInN1YiI6Im1lbmRlbGV5IiwiYXVkIjoid2lsZXkiLCJpYXQiOjE1NjgxMTA1MTgsImp0aSI6IjgzZDRmNjNhLTY0ODYtNDY1My1hYzBhLTFiZjNjODIxODNhZiIsImRvaSI6IjEyLjM0NS8yMDE4enoxMTIyMzMiLCJpZHAiOiJodHRwczovL2lkcC5leGFtcGxlLm9yZyJ9.UZ3Bax8HGMcRhZoThBmesXoE-RqFvLSDfOezA8LJWJ0

Resources

• https://jwt.io/#debugger-io
• https://mkjwk.org/
• https://www.unixtimeconverter.io/

Quality of Service (QoS)

Each request must include a X-API-KEY HTTP header, supplied by getFTR . This is to ensure all Integrators get the same Quality of Service, and no one Integrator overloads getFTR. Integrators should gracefully handle a 429 Response Code (Too Many Requests)

Each request must include a unique X-REQUEST-ID HTTP header which will be carried forward

X-REQUEST-ID: 3e5980ba-ceae-4976-a9d4-c7e6ac49a20b (GUID)

Major Versions

Major version changes result in a breaking change to the interface contract. The major version number (X below) is declared in the path as follows:

/vX/entitlement?doi={doi}

This specification is at version 1.0 and is reflected in the path as follows:

/v1/entitlement?doi={doi}

Minor Versions

Minor version changes result in a non-breaking change (e.g. additional SAML attribute support). The minor version is not reflected in the path.

Robustness

getFTR will conform completely to the specification, but Integrators must be able to accept input with any non-breaking changes. In other words:

“Be liberal in what you accept, be conservative in what you send”
(Postel’s Law, aka The Robustness Principle )

Encoding & Formatting

The following rules apply to Entitlement API request and response structures:

URL Encoding

All API URLs are constructed in compliance with RFC 3986 .

Single line JSON

The JSON body response must be single line, with no line feeds or carriage returns.

White space

No white space between properties and values in the JSON response.

Character Encoding

UTF-8 is the adopted character encoding standard.

Readability

To improve readability, in all worked examples, all responses are shown with prettyPrint enabled.

The Entitlement API specification adopts a number of open standards and patterns, outlined below:

All adopted HTTP headers are listed here:

Adopted JSON schema format: http://json-schema.org

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id":
  "http://getfulltextresearch.com/schema/entitlement-schema-1-0.json",
  "type": "object",
  "title": "Entitlement API Schema 1.0",
  "oneOf": [
    {
      "$ref": "#/entitledResponse"
    },
    {
      "$ref": "#/bavResponse"
    },
   {
      "$ref": "#/unentitledResponse"
    }
    ],
  "definitions": {
    "doi": {
      "$id": "#/definitions/doi",
      "type": "string"
      },
    "entitled": {
        "$id": "#/definitions/entitled",
        "type": "string",
        "enum": [
        "yes",
        "no",
        "maybe"
        ]
      },
    "accessType": {
        "$id": "#/definitions/accessType",
        "type": "string",
        "enum": [
        "open",
        "free", 
        "paid"
        ]
      },
    "contentType": {
        "$id": "#/definitions/contentType",
        "type": "string",
        "enum": [
        "application/pdf",
        "text/html",
        "application/epub+zip",
        "other"
       ]
     },
    "url": {
        "$id": "#/definitions/url",
        "type": "string",
        "format": "uri",
        "pattern": "^(https?|http?|ftps?|ftp?)://"
      },
     "entityID": { 
          "$id": "#/definitions/entityID",
          "$ref": "#/definitions/url"
        },
     "document": {
          "$id": "#/definitions/document", 
          "type": "object",
          "properties": {
          "contentType": {
          "$ref": "#/definitions/contentType"
       },
     "url": {
          "$ref": "#/definitions/url"
       }
     },
   "additionalProperties": false,
   "required": [
   "contentType",
   "url"
    ]
  },
    "documentArray": {
       "$id": "#/definitions/documentArray",
       "type": "array",
        "items": {
             "$ref": "#/definitions/document"
          }
       },
     "entitledResponse": {
          "$id": "#/entitledResponse",
              "properties": {
                   "entitled": {
                       "enum": [
                        "yes",
                        "maybe"
                        ]
                    },
              "doi": {
                    "$ref": "#/definitions/doi"
                   },
               "entityID": {
                     "$ref": "#/definitions/entityID"
                   },
               "accessType": {
                     "$ref": "#/definitions/accessType"
                   },
                "vor": {
                     "$ref": "#/definitions/documentArray"
                   },
                "document": {
                     "$ref": "#/definitions/url"
                   }
                },
           "additionalProperties": false,
           "required": [
                "entitled",
                "doi",
                "accessType",
                "vor",
                "document"
                ]
              },
           "bavResponse": {
                "$id": "#/bavResponse",
                "properties": {
                "entitled": {
                "const": "no"
              },
            "doi": {
                "$ref": "#/definitions/doi"
              },
            "entityID": {
                 "$ref": "#/definitions/entityID"
                },
            "bav": {
                 "$ref": "#/definitions/documentArray"
              },
            "document": {
                  "$ref": "#/definitions/url"
                }
             },
          "additionalProperties": false,
          "required": [
          "entitled",
          "doi",
          "bav",
          "document"
          ]
   },
     "unentitledResponse": {
        "$id": "#/unentitledResponse",
         "properties": {
            "entitled": {
               "const": "no"
   },
     "doi": {
        "$ref": "#/definitions/doi"
   },
     "entityID": {
      "$ref": "#/definitions/entityID"
    },
     "document": {
       "$ref": "#/definitions/url"
     }
   },
    "additionalProperties": false,
    "required": [
    "entitled",
    "doi",
    "document"
    ]
    }
  }
}

https://jsonschemalint.com