docs/admin/ebook_api.adoc

   1 Ebook API integration
   2 ---------------------
   3
   4 Evergreen supports integration with third-party APIs provided by OverDrive and
   5 OneClickdigital.
   6
   7 When ebook API integration is enabled, the following features are supported:
   8
   9  * Bibliographic records from these vendors that appear in your
  10 public catalog will include vendor holdings and availability information.
  11  * Patrons can check out and place holds on OverDrive and OneClickdigital ebook
  12 titles from within the public catalog.
  13  * When a user is logged in, the public catalog dashboard and My Account
  14 interface will include information about that user's checkouts and holds for
  15 supported vendors.
  16
  17 [WARNING]
  18 --
  19 The ability to check out and place holds on ebook titles is an experimental
  20 feature in 3.0.  It is not recommended for production use without careful
  21 testing.
  22 --
  23
  24 For API integration to work, you need to request API access from the
  25 vendor and configure your Evergreen system according to the instructions
  26 below.  You also need to configure the new `open-ils.ebook_api` service.
  27
  28 This feature assumes that you are importing MARC records supplied by the
  29 vendor into your Evergreen system, using Vandelay or some other MARC
  30 import method.  This feature does not search the vendor's online
  31 collections or automatically import vendor records into your system; it
  32 merely augments records that are already in Evergreen.
  33
  34 A future Evergreen release will add the ability for users to check out
  35 titles, place holds, etc., directly via the public catalog.
  36
  37 Ebook API service configuration
  38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39 This feature uses the new `open-ils.ebook_api` OpenSRF service.  This
  40 service must be configured in your `opensrf.xml` and `opensrf_core.xml`
  41 config files for ebook API integration to work.  See
  42 `opensrf.xml.example` and `opensrf_core.xml.example` for guidance.
  43
  44 OverDrive API integration
  45 ~~~~~~~~~~~~~~~~~~~~~~~~~
  46 Before enabling OverDrive API integration, you will need to request API
  47 access from OverDrive.  OverDrive will provide the values to be used for
  48 the following new org unit settings:
  49
  50   * *OverDrive Basic Token*: The basic token used for API client
  51     authentication.  To generate your basic token, combine your client
  52     key and client secret provided by OverDrive into a single string
  53     ("key:secret"), and then base64-encode that string.  On Linux, you
  54     can use the following command: `echo -n "key:secret" | base64 -`
  55   * *OverDrive Account ID*: The account ID (a.k.a. library ID) for your
  56     OverDrive API account.
  57   * *OverDrive Website ID*: The website ID for your OverDrive API
  58     account.
  59   * *OverDrive Authorization Name*: The authorization name (a.k.a.
  60     library name) designated by OverDrive for your library.  If your
  61     OverDrive subscription includes multiple Evergreen libraries, you
  62     will need to add a separate value for this setting for each
  63     participating library.
  64   * *OverDrive Password Required*: If your library's OverDrive
  65     subscription requires the patron's PIN (password) to be provided
  66     during patron authentication, set this setting to "true."  If you do
  67     not require the patron's PIN for OverDrive authentication, set this
  68     setting to "false."  (If set to "true," the password entered by a
  69     patron when logging into the public catalog will be cached in plain text in
  70     memcached.)
  71   * *OverDrive Discovery API Base URI* and *OverDrive Circulation API
  72     Base URI*: By default, Evergreen uses OverDrive's production API, so
  73     you should not need to set a value for these settings.  If you want
  74     to use OverDrive's integration environment, you will need to add the
  75     appropriate base URIs for the discovery and circulation APIs.  See
  76     OverDrive's developer documentation for details.
  77   * *OverDrive Granted Authorization Redirect URI*: Evergreen does not
  78     currently support granted authorization with OverDrive, so this
  79     setting is not currently in use.
  80
  81 For more information, consult the
  82 https://developer.overdrive.com/docs/getting-started[OverDrive API
  83 documentation].
  84
  85 To enable OverDrive API integration, adjust the following public catalog settings
  86 in `config.tt2`:
  87
  88   * `ebook_api.enabled`: set to "true".
  89   * `ebook_api.overdrive.enabled`: set to "true".
  90   * `ebook_api.overdrive.base_uris`: list of regular expressions
  91     matching OverDrive URLs found in the 856$9 field of older OverDrive
  92     MARC records.  As of fall 2016, OverDrive's URL format has changed,
  93     and the record identifier is now found in the 037$a field of their
  94     MARC records, with "OverDrive" in 037$b.  Evergreen will check the
  95     037 field for OverDrive record identifiers; if your system includes
  96     older-style OverDrive records with the record identifier embedded in
  97     the 856 URL, you need to specify URL patterns with this setting.
  98
  99 OneClickdigital API integration
 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 101 Before enabling OneClickdigital API integration, you will need to
 102 request API access from OneClickdigital.  OneClickdigital will provide
 103 the values to be used for the following new org unit settings:
 104
 105   * *OneClickdigital Library ID*: The identifier assigned to your
 106     library by OneClickdigital.
 107   * *OneClickdigital Basic Token*: Your client authentication token,
 108     supplied by OneClickdigital when you request access to their API.
 109
 110 For more information, consult the
 111 http://developer.oneclickdigital.us/[OneClickdigital API documentation].
 112
 113 To enable OneClickdigital API integration, adjust the following public catalog
 114 settings in `config.tt2`:
 115
 116   * `ebook_api.enabled`: set to "true".
 117   * `ebook_api.oneclickdigital.enabled`: set to "true".
 118   * `ebook_api.oneclickdigital.base_uris`: list of regular expressions
 119     matching OneClickdigital URLs found in the 859$9 field of your MARC
 120     records.  Evergreen uses the patterns specified here to extract
 121     record identifiers for OneClickdigital titles.
 122
 123 Additional configuration
 124 ~~~~~~~~~~~~~~~~~~~~~~~~
 125 Evergreen communicates with third-party vendor APIs using the new
 126 `OpenILS::Utils::HTTPClient` module.  This module is configured using
 127 settings in `opensrf.xml`.  The default settings should work for most
 128 environments by default, but you may need to specify a custom location
 129 for the CA certificates installed on your server.  You can also disable
 130 SSL certificate verification on HTTPClient requests altogether, but
 131 doing so is emphatically discouraged.