1. M25 Consortium Avatar M25 Consortium
  2. Untitled project
  3. api25

Wiki

Clone wiki

api25 / Home

View History

API Operations

The API is RESTful, using HTTP commands to distinguish different operations. Only GET operations are open to all users; PUT, POST, and DELETE, which change the database content are blocked from remote hosts. All GET operations can have a mimetype descriptor appended. The mimetypes currently supported are json and xml. The default is xml, which is returned if no mimetype is specified. The API currently ignores mimetypes specified in the ACCEPT header field.

Some of the operations can have parameters; these are listed below and explained on the separate pages for each operation

GET Operations

  • info.xml - returns a statement explaing the copyright status of data from this API and a list of valid GET operations. The same list of operations is returned whenever an invalid command is sent.

The following operations return data describing a resource or set of resources

The next set of operations relate to user permissions to access different libraries

  • schemes[.xml|json] - lists the access schemes relevant to M25 institutions
  • schemes/{id}[.xml|json] - gives details of a single access scheme
  • schemes/{id}/institutions[.xml|json]?active=[nil|true|false] - lists the institutions enrolled in a particular access scheme
  • roles[.xml|json] - lists all personal roles considered relevant to library access
  • institutions/{code}/agreements[.xml|json] - list all access rules applying to an institution
  • institutions/{code}/entitlements[.xml|json]?code=[m25|copac|isil|sconul]&affiliation=role@institutional_domain - access rights for a person with a role at an institution at another institution
  • entitlements/{id}/institutions[.xml|json]?affiliation=role@institutional_domain - institutions at which a person with a role in another institution has a particular access right

The following operations return form data. The form may be pre-populated (for editing existing entries) or not (for new entries). The idea behind forms is described here. Forms are driven by a textual configuration file with defined semantics. Working commands are listed below: commands without an id return empty form data to be populated by the user in order to create a new object using a PUT or POST command; commands with an id return a form plus the exisitng data for the item for editing.

  • schemes/form[.xml|.json]
  • schemes/{id}/form[.xml|.json]
  • institutions/form[.xml|.json]
  • institutions/{code}/form[.xml|.json]
  • libraries/form[.xml|.json]
  • institutions/{code}/libraries/{id}/form[.xml|.json]
  • z3950server/form[.xml|.json]
  • institutions/{m25_code}/z3950server/{id}/form[.xml|.json]
  • agreements/form[.xml|.json]
  • agreements/{id}/form[.xml|.json]

PUT Operations

These operations modify an existing resource or create a new resource where the id is already given (eg a new m25_code, which has to be determined by the administrator and not automatically generated by software). PUT operations can be repeated without side-effects (eg. submitting a new resource twice will only create one database entry for the resource). The data must be submitted in the format returned by the GET 'form' operations. Some update operations trigger cascades in the database.

POST Operations

These operations create a new resource where the id is automatically generated. The id is returned in the Location field of the HTTP header. Repeating a POST operation will generate multiple entries in the database. The data must be submitted in the format returned by the GET 'form' operations. Some update operations trigger cascades in the database.

DELETE OPERATIONS

These operations may trigger cascades in the Database.

Updated