Public Lookup API

Owned by Owen Stephens
Jun 29, 2023
2 min read

In order to make it possible to display license terms to users in public facing systems (e.g. a discovery system) a publicly accessible API endpoint is available for the Agreements application which returns information on publicly viewable license terms for a particular resource (based on the agreements the resource belongs to).

This was implemented via ERM-356 - Getting issue details... STATUS

The endpoint and full path is `erm/sas/publicLookup`

The endpoint also supports the parameters: `referenceId` and `resourceId` (which both just effectively prepoulate some filters/matches)

For a eHoldings resource it can be used as follows:

  • /erm/sas/publicLookup?referenceId=18-34-32090  find all agreements with that resource as part of it (i.e. there is either an agreement line for the resource or for the package the resource belongs to)
  • /erm/sas/publicLookup?referenceId=18-34  find all agreements specifically with the package (i.e. only cases where the agreement line is for the package)

For an internal KB resource, the resource ID (UUID) for the Title Instance (TI), Platform Title Instance (PTI) or Package Content Item (PCI) or Package  can be supplied for any of our resources:

  • `/erm/sas/publicLookup?resourceId=7549b408-e2ff-41cb-b412-32de9e82e9eb`

This behaves as follows:

  • If the resourceId represents a TI then it will find all agreements which include this title instance (whether via the package or directly)
  • If the resourceId represents a PTI then it will find all agreements which include this platform title instance (whether via the package or directly)
  • If the resourceId represents a PCI then it will find all agreements which include this package content item (whether via the package or directly)
  • If the resourceId represents a Package then it will only find agreements which include the package directly

Additionally you can further filter the results by aspects of the agreement. You can supply the following (all as encoded url parameters):
`term` = term to search by
`match` = properties of the agreement to match
`filters` = any additional filters
`sort` = properties to sort by
`offset` or `page`
`max` or `perPage`

The `term`, `match`, `filters`, `sort` can only be used on the data stored directly on the agreement. So for example:

/erm/sas/publicLookup?resourceId=7549b408-e2ff-41cb-b412-32de9e82e9eb&filters=endDate%3E%3D2023-06-29 

will only return agreements (and their license terms) which contain the resource identified by 7549b408-e2ff-41cb-b412-32de9e82e9eb and have an endDate on 29th June 2023 or later