This directory includes some sample code for calling the
Annotate API.
The sample code is fairly basic and intended
to demonstrate the process of calling the web APIs; writing equivalents
in languages other than PHP should be straightforward.
(for Java programmers: There is a basic example for Java too:
the java/ subdirectory includes a sample
AnnotateApi.java
for signing an Annotate API request from Java and parsing the JSON
response.)
You need to create a configuration file: test_config.php file before running any of the tests. A sample is provided in 'test_config.orig' so first of all:
cp test_config.orig test_config.php vi test_config.php # or your preferred text editor...
The apiuser should be set to the email of the
admin user of your Annotate installation, and the apikey
is displayed at the bottom of the apiuser's a.nnotate account page.
(if you don't see the apikey on your account page, check
that the setting $enableapi = 1; is present
in your php/config.tmp file).
You can change the
sampleDate and sampleCode once you have uploaded
a document, as they are used in the later tests. The sampleWS is
also needed for several tests.
$apiuser = "you@yoursite.com"; $apikey = "iMMbpfKyRPm5s3n8zayr8RPT8chhLZvk"; $annotateServer = "http://localhost/annotate"; // The sample annotate user. $sampleUser = "joe@example.com"; $sampleSig = "joe"; // Another sample user. $sampleUser2 = "jill@example.com"; $sampleSig2 = "jill"; // Sample document date / code: // *** Replace these with the values returned after uploading a document *** $sampleDate = "2008-07-15"; $sampleCode = "jIKdZcO2"; // Sample workspace id: // *** Replace this with an existing workspace id *** $sampleWS = "114918322";
# Configuration settings
# Important: Edit this before running any tests
test_config.php
# Utility functions
HMAC.php --- Crypt_HMAC class to calculate hashes for signing requests
JSON.php --- json_encode and json_decode functions
annotateApi.php --- signRequest() function for signing API requests
# HTML samples (view these in browser)
html_uploadDocument.php --- upload a document
html_updateDocumentMeta.php --- edit document level notes / tags / title
html_viewSample.php --- view a document
html_addNote.php --- add a note
html_loginAs.php --- login as a given A.nnotate user
html_error.php --- display an error message
# Test PHP samples (run from command line)
test_createAccount.php --- create an Annotate account via API
test_updateAccount.php --- change account settings
test_deleteDocument.php --- delete a document
test_listDocuments.php --- display a list of documents {+metadata/notes} for a user
test_listFolders.php --- list folders for a user
test_listNotes.php --- list notes for a document
test_listUsers.php --- list user accounts
The test scripts all include the annotateApi.php utility functions which includes the definition of signRequest(), used to add a hash code to authenticate API requests.
You may find it useful to check the Amazon S3 Web Services sample code for equivalent libraries in other languages (Java / ASP etc), as the authentication mechanism used for the Annotate API is similar to that used for S3.
The samples starting test_... are intended to be run from the command line. The samples starting html_... are intended to be viewed in a browser.
From the command line...
php test_createAccount.php
--- creates new accounts for the two sample users specified in 'test_config.php'
Accounts are initially created as 'annotators' - to license them to upload documents, you need to call updateAccount.php. This can also be used to change the short signature used to sign notes, and the user's a.nnotate password.
php test_updateAccount.php
You can check that the accounts have been added by viewing your system admin page (php/serverAdmin.php in your installation, there's a link from your account page too when logged in as the admin user).
You can use the API to create links from your web application to log users in to their a.nnotate account automatically. This can be useful if you already have your own user authentication system and do not want users to have to log in separately to A.nnotate. The html_loginAs.php sample lets you authenticate as a particular user and then display the list of documents, notes, or a particular document. Login as sample users with the link: html_loginAs.php
Open the browser at html_uploadDocument.php
and browse for a PDF document to try uploading. It should display a message like OK 2008-01-01 abc123. You could use the return values to set the $sampleDate and $sampleCode values
in the test_config.php file to the uploaded document.
Once you've edited the $sampleCode and $sampleDate settings in your test_config.php, you can point the browser at html_viewSample.php to make a public link to the document.
The html_addNote.php sample lets you add notes to PDF documents using the API. It uses a HTTP POST with a number of parameters (note text, where it is attached etc). After adding a note, you might want to html_viewSample.php again and press 'reload' to see it.
The html_updateDocumentMeta.php sample lets you edit the document's metadata (title, tags, notes, authors). It uses a HTTP POST. The values you set will overwrite any previous values. After saving the metadata, you may wish to html_viewSample.php and use the Tools > properties menu to check that the metadata has been updated. This call can also be used to set annotation permissions on a document, to restrict to particular users or pages.
The test_listDocuments.php sample lists the documents in a given workspace , returned as a JSON array. The parameters are the start / end month, and you can choose whether to return the extended document level metadata and notes along with the basic date / code / name. Run this sample (and all the test_... samples) from the command line:
php test_listDocuments.php
You can fetch the notes on a single document using test_listNotes.php. It returns a JSON array which includes the document metadata as well as the notes.
php test_listNotes.php
test_listUsers.php lists the email addresses of the a.nnotate accounts you administer. The return value is a JSON object with two array fields "members" and "annotators", both arrays of email addresses.
php test_listUsers.php
The test_deleteDocument.php sample shows how to remove a document from a user's list.
# you may want to wait until you've run the other tests # before deleting the sample document... php test_deleteDocument.php
View html_createFolder.php to create a new folder in the test user's account.
You can list a user's folders as a JSON object using:
php test_listFolders.php
View html_deleteFolder.php to delete a folder given its ID.
View html_moveDocument.php to move a document to a given folder id.
View html_moveFolder.php to move a folder to a given folder id.
View html_setFolderTags.php to set the list of available note tags for a folder.
View html_getFolderTags.php to get the list of available note tags for a folder.
View html_renameFolder.php to rename a folder.