Wiki
Clone wikiapi25 / Home
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
- institutions[.xml|json]?active=[nil|true|false] - lists institutions in the M25 consortium
- institutions/{code}[.xml|json]?code=[nil|m25|copac|isil|sconul] - gives details of a single institution in the consortium
- institutions/{code}/libraries[.xml|json]?code=[m25|copac|isil|sconul] - gives details of all libraries in a single institution
- institutions/{code}/libraries/{id}[.xml|json] - gives details of a single library
- institutions/{code}/subjects[.xml|json]?code=[m25|copac|isil|sconul] - lists subjects covered by libraries in a single institution
- institutions/{code}/libraries/{id}/subjects[.xml|json]?code=[m25|copac|isil|sconul] - lists subjects covered by one library
- z3950server[.xml|json]?active=[nil|true|false]&source_type=[library|uls|archive] - lists z39.50 servers
- institutions/{code}/z3950server[.xml|json]?active=[nil|true|false] - lists z39.50 servers for a single institution
- libraries[.xml|json]?active=[nil|true|false] - lists all libraries
- subjects[.xml|json] - lists all subjects registered to M25 libraries
- subjects/{id}[.xml|json] - gives details of a single subject
- subjects/{id}/institutions[.xml|json]?active=[nil|true|false] - lists the institutions with libraries that cover a particular subject
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.
- institutions/{code} - create or update an institution
- institutions/{code}/libraries/{id} - update a library
- institutions/{code}/z3950server?z39_name={name} - create or update a Z39.50 server
- schemes/{id}[.xml|json] - create or update an access scheme
- institutions/{code}/agreements/{id} - update an access rule applying to an institution
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.
- institutions/{code}/libraries - create a library
- institutions/{code}/agreements - create an access rule applying to an institution
DELETE OPERATIONS
These operations may trigger cascades in the Database.
- institutions/{code} - delete an institution
- institutions/{code}/libraries/{id} - delete a library
- institutions/{code}/z3950server?z39_name={name} - delete the named z39.50 server
- schemes/{id} - delete an access scheme
- institutions/{code}/agreements/{id} - delete an access rule applying to an institution
Updated