This API exposes the majority of RefWorks functionality in a REST format. The API is divided into several classes. Each class handles a specific category of RefWorks functionality. Within each class, there are one or more methods that provide specific functionality within a given class. For instance to perform a Google-like search on a specific account you would make a call to the quick
method of the Retrieve
Format of REST Call
Each call is broken into four sections: Base URL
, Call Signature
, Call Specific
and Session ID
- Base URL
- Call Signature
- Each call is authenticated via a call signature which is created based on a RefWorks assigned AccessKeyID, SecretCode and other parameters. This is described below in more detail.
- Call Specific
- Always includes at least a "class" and "method" parameter.
- Session ID
- Each Session is initiated with a call to newsess which returns a Session ID. Session ID are valid for up to 20 minutes after the last API call. The session id then must be passed in the
sess parameter in all subsequent calls. The newsess function is one of the few API calls that does not require a Session ID
Signature - Authenticating REST Request
Each REST call must pass a Signature which is compared with a signature created on the server. If the 2 match than access is granted. A user of the Web services is provided an AccessKeyID which uniquely identifies auser. Also provided with this AccessKeyID is a Secret Access key which should be kept private by the user. Note that this is very similar to the signature used in Amazons S3 technology.
|Query String Parameter||example value||description|
|expires||1224866080931||The time when the signature expires, specified as the number of milliseconds since the epoch (00:00:00 UTC on January 1, 1970). A request received after this time (according to the server), will be rejected. Note that an allowance of 5 minutes is made to account for server synchronization issues.|
|signature||qMUcsnrYm3CvmGkO5/rqiSkd0CE||The URI encoded signature which is describe in detail below|
The Signature is created by concatenating <class of call>+ <AccessKeyID> + <expires>
and then running the result through a Base64 encoding of the HMAC-SHA1, passing it <secret Access Key> as the encoding key
Below is an example of the parameters passed for a call to class=retrieve
with a Secret Access Key = dfgwv$djfhe108
If any aspect of the Signature authentication is incorrect the REST call will return a HTTP status value of 400 with a detailed description of the issue so as to aid the developer in debugging the issue.
All responses begin with an RWResult element. This element contains the result, the processTime and a detail result message attributes. The RWResult contains a CallInfo element which gives more generic details about the call. This is then followed by function specific XML element which is defined in the function's documentation.
C O N F I D E N T I A L