The Purchase API uses client signing in order to secure your data and prevent any malicious requests. The steps below indicate how to use your API keys to sign your request and successfully authenticate. For complete code examples, see the appendix.
Task 1: Generate a checksum for the request content
In order to allow verification of the content of your request, you need to provide a SHA-256 checksum of your message content. In the pseudo-code below, the message_content variable contains the contents of the message you plan to send (this is the message body, without any headers). If your message content is empty (as is often the case for GET requests), substitute an empty string '' for the content:
Pseudocode for generating a message content checksum:
content_checksum = HexEncode(SHA256(message_content))
Sample content checksum for the string "sample payload":
Task 2: Collect Signature Elements
The unsigned request consists of a number of elements that you concatenate together into a single string ready for signing.
The first element is the request type you wish to use (GET, PUT, POST, DELETE) in all upper-case.
The second element is the URI of the request itself, in canonical form. The canonical URI is the URI-encoded version of everything in the URI from the HTTP host, including any question mark character (?) and all query string parameters (if any). Normalize URI paths according to RFC 3986 by removing redundant and relative path components and convert everything to lower-case (except where upper-case is required in any parameters). In our case, we have:
The third element exists to reduce the possibility of replay attacks (someone submitting your request again at a future time). To create this element, you construct a string containing the timestamp for this request. This timestamp should be expressed in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) using UTC. Your request is valid for five minutes from this timestamp.
The fourth element is the content_checksum calculated in Task 1.
Task 3: Create the final string
To generate the final string used to create a request signature, you must concatenate all of these elements together, placing a single newline character between each. Using the examples above, pseudo-code to create the final string would be:
action = 'POST' uri = 'https://purchase.api.abebooks.com/v1/orders' abe_date = '2017-09-18T23:25:35Z' content_checksum = 'eee57820203860ea469843dfba7bbb970021cae59fcc6e99056937bdec33fd02' final_string = action + '\n' + uri + '\n' + abe_date + '\n' + content_checksum
Task 4: Generate the request signature
Before you can sign the final string, you will need a set of valid Purchase API credentials. These credentials consist of an access-key and a secret-key which can be obtained from https://www.abebooks.com/servlet/PurchaseApiKeys. In this example, assume the following credentials were obtained:
secret_key = '9ea20986-8f49-42f1-aa27-63EXAMPLEKEY' access_key = 'EXAMPLEACCESSKEY'
Once you have the final string prepared, you generate the request signature by using the secret-key with a SHA-256 HMAC algorithm. Using the final_string from the code above, Pseudo-code is shown below
abe_signature = HMAC(secret_key, final_string, hashlib.sha256).hexdigest()
Signature for the example in Task 3:
Task 5: Submit the Request
With the signature in hand, you are ready to submit your request to the API. To do so, call the API with the appropriate request type (GET, POST) as used in your signing, and request the URI you signed, including all parameters. In your request, provide three extra headers. The first is the Abe-Date that you used during the signature. The second is your Purchase API access-key Abe-Access-Key. The third is the Abe-Signature which you calculated above. Finally in Abe-RequestId you must include a unique ID that can be used to reference the request. (It is strongly recommended to use GUIDs for this purpose.)
The full HTTP request for the example shown above will look something like the following:
POST https://purchase.api.abebooks.com/v1/orders' HTTP/1.1 Abe-Date: 2017-09-18T23:25:35Z Abe-Access-Key: EXAMPLEACCESSKEY Abe-Signature: 9b6156bdd88cddf86fee8bab59533fdb23bf3887a890b62bba606d36396e6100 Abe-RequestId: f27d1de5-e37e-4760-b00c-d539cd7ce68e sample content