Your gateway to millions of microforms and digital reproductions of books
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
get_involved-promote_your_collections-eromm_request-api [2011-09-02, 16:17] schleier [EROMM Request API] |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== EROMM Request API ====== | ||
| - | **//Please note: This page is still in development.//** | ||
| - | |||
| - | With just a little scripting, you can plug EROMM Request into your local Document Order and Delivery System or ILS or even build your own application to maintain your incoming requests. The EROMM Request API consists of a number of (RESTful) webservices which will return JSON objects as default (or HTML if you explicitly ask for it). | ||
| - | |||
| - | Supported HTTP commands are ''GET'' and ''POST'', which can be used alike. You may either use querystring parameters in your HTTP-requests or pack the parameters into a JSON object, which is then handed over as the value of the parameter ''data''. If you use both variants in one request, the querystring parameters will take precedence over the JSON encoded values if there is a conflict. | ||
| - | |||
| - | **Please note:** Please consider this API sort of "beta". We might change a thing or fix a bug in the future and will announce it on the EROMM Website accordingly. If you let us know, that you are using the API, we could inform you directly in advance. Please note also that this documentation documents only these parts of the API that are needed on the supplier (i.e. the library or institution holding a microfilm or digital item a user might be interested in) side. We might publish the other parts at a later point in time. | ||
| - | |||
| - | ===== General ===== | ||
| - | **Common parameters for all API calls:** | ||
| - | |cmd|Command|indicates the action that should be carried out.| | ||
| - | |auth|Authentication Token| Any action that requires the client to be authenticated, needs an authentication token being sent with the request. This token is obtained by performing a login operation.| | ||
| - | |format|Output format|Specifies the response format of the API call. Currently ''json'' and ''html'' are supported, with ''json'' being the default if no format indication is given.| | ||
| - | |||
| - | **Response format:** | ||
| - | |||
| - | <code> | ||
| - | { | ||
| - | "auth":{ | ||
| - | "add_associated_supplier":"0", | ||
| - | "create_user":"1", | ||
| - | "add_message":"1", | ||
| - | "change_request":"1", | ||
| - | "supplier":"2350", | ||
| - | "user":null, | ||
| - | "is_admin":"0", | ||
| - | "read":"1", | ||
| - | "expires":"2011-07-22 14:57:19" | ||
| - | }, | ||
| - | "verbose":{ | ||
| - | "supplier":{ | ||
| - | "info":"This is the test account of the EROMM Secretariat\u000d\u000aWe do not deliver any items.", | ||
| - | "website":"http://www.sub.uni-goettingen.de", | ||
| - | "isil":"DE-7", | ||
| - | "name":"EROMM TEST", | ||
| - | "address":"Platz der Göttinger Sieben 1\u000d\u000a37081 Göttingen\u000d\u000aGermany" | ||
| - | }, | ||
| - | "user":{ | ||
| - | "email":"jahnke@sub.uni-goettingen.de", | ||
| - | "name":"Tester, Theo", | ||
| - | "address":"Papendiek 14\u000a37073 Göttingen\u000aGermany" | ||
| - | }, | ||
| - | "title":{ | ||
| - | "ppn":"483278114", | ||
| - | "sVolume":null, | ||
| - | "erommId":"USRLINNJPG85-B21371", | ||
| - | "sSeries":null, | ||
| - | "sPhysicalDescription":"1 microfilm reel", | ||
| - | "sLocation":"US ; Princeton University Library : shelfmark unknown", | ||
| - | "pImprint":"[Augsburg] : [s.n.], [1881]", | ||
| - | "pSeries":null, | ||
| - | "pTitleSet":null, | ||
| - | "sImprint":"[Princeton, N.J.] : Princeton University Library, 1982", | ||
| - | "type":1, | ||
| - | "pTitle":"Hainhofers Reisen nach München und Neuberg a/D in den Jahren 1613, 1614 und 1636", | ||
| - | "pAuthor":"Hainhofer, Philipp" | ||
| - | } | ||
| - | }, | ||
| - | "errors":[], | ||
| - | "data":{ | ||
| - | "request":"9", | ||
| - | "messages":[{ | ||
| - | "request":"9", | ||
| - | "text":"What would be the price for a printout of this publication?", | ||
| - | "sender":"10009", | ||
| - | "requestType":"1", | ||
| - | "dateCreated":"2011-07-22", | ||
| - | "message":"36" | ||
| - | } | ||
| - | ], | ||
| - | "status":"3", | ||
| - | "replyBy":"2011-08-01", | ||
| - | "discount":"0", | ||
| - | "dateChanged":"2011-07-22", | ||
| - | "supplier":"2350", | ||
| - | "user":"10009", | ||
| - | "title":"483278114", | ||
| - | "material":"1", | ||
| - | "dateCreated":"2011-07-22" | ||
| - | }, | ||
| - | "token":"ymUKf8AwcCjIFfdLAdCBkAu5iuvYYbFQ" | ||
| - | } | ||
| - | </code> | ||
| - | |||
| - | ==== Properties of the response object ==== | ||
| - | |//auth.add_associated_supplier//|true if the holder of the login account has the necessary privileges to associate users with a supplier account (e.g. in order to entitle them to a discount)| | ||
| - | |//auth.add_message//|true if the account has the necessary privileges to add messages to the requests associated with the connected user or supplier account| | ||
| - | |//auth.change_request//|true if the account holder has the necessary privileges to change a request associated with the connected user or supplier account| | ||
| - | |//auth.create_user//|true if the holder of the login account can create a user account associated with the login account| | ||
| - | |//auth.expires//|date and time when the current authentication token expires| | ||
| - | |//auth.is_admin//|true if the holder of the login account has admin privileges| | ||
| - | |//auth.read//|true if the holder of the login account has the necessary privileges to read the requests associated with the connected user or supplier account| | ||
| - | |//auth.supplier//|Supplier ID associated with the current login| | ||
| - | |//auth.user//|User ID associated with the current login| | ||
| - | |//data//|In response to a call that lists requests (e.g. new requests, updated requests etc.) the request information is given in a list of objects in the //data// property. The properties used are the same as for a single request, except that //verbose// and //data.messages// are not included| | ||
| - | |//data.messages.[].dateCreated//|Date on which the message has been created| | ||
| - | |//data.messages.[].message//|Message ID| | ||
| - | |//data.messages.[].request//|Request to which the message applies| | ||
| - | |//data.messages.[].requestType//|Code for the type of request| | ||
| - | |//data.messages.[].sender//|User/Supplier ID of the sender of the given message| | ||
| - | |//data.messages.[].text//|Text of the message| | ||
| - | |//data.request//|Request ID| | ||
| - | |//dateChanged//|date on which the request has last been changed| | ||
| - | |//dateCreated//|date on which the request has been created| | ||
| - | |//discount//|true if the user is entitled to a 5% discount off the regular fee for a use copy (according to Memorandum of Understanding)| | ||
| - | |//material//|code that indicates the type of material the request is about: ''1'' for microfoms and ''2'' for digital material| | ||
| - | |//replyBy//|the date after which the system will try to send out a reminder to both the user and the supplier unless the request has not reached a final status by then| | ||
| - | |//status//|the status of the request| | ||
| - | |//supplier//|ID of the supplying institution (for full information see //verbose.supplier//)| | ||
| - | |//title//|the id of the title, the request is about (for full information see //verbose.title//)| | ||
| - | |//token//|the current authentication token| | ||
| - | |//user//|ID of the user who initiated the request (for full information see //verbose.user//)| | ||
| - | |//verbose.supplier.address//|Address of the supplying institution| | ||
| - | |//verbose.supplier.info//|Short information on the supplying institution| | ||
| - | |//verbose.supplier.isil//|ISIL of the supplying institution, if the supplying institution is a library| | ||
| - | |//verbose.supplier.name//|name of the supplying institution| | ||
| - | |//verbose.supplier.website//|Website of the supplying institution| | ||
| - | |//verbose.title.erommId//|ID assigend to that surrogate by EROMM| | ||
| - | |//verbose.title.pAuthor//|Author of the original publication| | ||
| - | |//verbose.title.pImprint//|Imprint statement of the original publication| | ||
| - | |//verbose.title.ppn//|Internal identifier for the surrogate in the EROMM Classic database| | ||
| - | |//verbose.title.pSeries//|Title of the series, the original publication is part of| | ||
| - | |//verbose.title.pTitle//|Title of the publication| | ||
| - | |//verbose.title.pTitleSet//|Collective title of the mulit-volume work the original publication is part of| | ||
| - | |//verbose.title.sImprint//|Imprint statement of the surrogate| | ||
| - | |//verbose.title.sLocation//|Location of the surrogate (library and shelfmark)| | ||
| - | |//verbose.title.sPhysicalDescription//|physical description of the surrogate| | ||
| - | |//verbose.title.sSeries//|Title of the reprodction series, the item is part of| | ||
| - | |//verbose.title.sVolume//|Volume number if the item is part of a reproduction series| | ||
| - | |//verbose.title.type//|code that indicates the type of material (''1'' for microform, ''2'' for digital)| | ||
| - | |//verbose.user.address//|Address of the user who initiated the request| | ||
| - | |//verbose.user.email//|Email-Address of the user who initiated the request| | ||
| - | |//verbose.user.name//|Name of the user who initiated the request| | ||
| - | |||
| - | ===== Authentication ===== | ||
| - | === login === | ||
| - | ^Script |''login.pl''| | ||
| - | ^Command| //login//| | ||
| - | ^Authentication required |no| | ||
| - | ^Specific Parameters |''login'' contains the login name (user name) \\ ''password'' holds the password| | ||
| - | ^Return Value|This service returns an authentication token which is required for all other webservices. The authentication token times out after 30 minutes of inactivity. The token is returned as the token property of the returned JSON object| | ||
| - | ^Example |login.pl?cmd=login&login=<login name>&password=<password>| | ||
| - | |||
| - | === logout === | ||
| - | ^Script |''login.pl''| | ||
| - | ^Command|//logout//| | ||
| - | ^Authentication required |yes| | ||
| - | ^Specific Parameters | none| | ||
| - | ^Return Value|The token property of the returned JSON object is ''null''| | ||
| - | ^Example |login.pl?cmd=logout&auth=<authentication token> | | ||
| - | |||
| - | ===== Handling Requests ===== | ||
| - | |||
| - | === activateRequest === | ||
| - | === addMessage === | ||
| - | === cancelRequest === | ||
| - | === closeRequest === | ||
| - | === confirmRequest === | ||
| - | === displayRequest === | ||
| - | === listRequests === | ||
| - | === listCancelledRequests === | ||
| - | === listClosedRequests === | ||
| - | === listNewRequests === | ||
| - | === listOpenRequests === | ||
| - | === listRedirectedRequests === | ||
| - | === redirectToAdmin === | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | ===== Handling Supplier Information ===== | ||
| - | === addAssociatedUser === | ||
| - | === getDeliveryDetails === | ||
| - | === getSupplier === | ||
| - | === listAssociatedUsers === | ||
| - | === removeAssociatedUser === | ||
| - | === updateDeliveryDetails === | ||
| - | === updateSupplier === | ||
Last modified:: 2012-04-12, 11:01