RefWorks API - Reference Guide

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 class.

Each call is broken into four sections: Base URL, Call Signature, Call Specific and Session ID.

Base URL: www.refworks.com/api2/
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

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
accesskeyid	wd$3wrfderddml	Your AccessKeyID.
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
For example, if your Secret Access Key = dfgwv$djfhe108, your AccessKeyID = wd$3wrfderddml and you are making a call to class=retrieve you should get the following signature:

class=retrieve&accesskeyid=wd$3wrfderddml&expires=1224873890294&signature=SAvNT7%2Fq9R3TflOqzaTSfB%2B6VJg%3D

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.