A.nnotate API reference - Part 2
This is Part 2 of the A.nnotate API reference guide (see also Part 1 - Introduction and Part 3 - Folders). It includes calls to create accounts, upload documents, add notes, and allow authorized users to annotate particular documents.
- 1. createAccount.php - Creating user accounts
- 2. updateAccount.php - Licensing / updating user accounts
- 3. loginAs.php - Login as a given user and display the given A.nnotate page
- 4. uploadDocument.php - Uploading a document
- 5. addNote.php - Adding a note to a document
- 6. updateDocumentMeta.php - Editing document metadata and permissions
- 7. deleteDocument.php - Removing a document from a user's list
- 8. authorizeReader.php - Authorizing a reader to view a document
- 9. listUsers.php - Listing user accounts
1. Create a new user account
The createAccount.php call allows you to create a user account. The request must be signed by the api-user (see authentication. Accounts are initially created as 'annotating users' - to allow the user to upload documents, see the next section.
http://yoursite.com/annotate/php/createAccount.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user's account
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&sig=jill # The user's signature
&tagsfile=inittags # (optional) init user tags from php/inittags.txt
The return value is either "OK" or "ERR {error message}".
Setting the initial set of available note tags: The optional tagsfile parameter can be set to load initial note tags from a file tagsfile.txt in the php/ directory. The default is to use 'php/inittags.txt' - if you want to initialise the tags to the contents of 'php/mytags.txt', set tagsfile=mytags (i.e. without the .txt extension)
2. Licensing / updating user accounts
The updateAccount.php call lets you change user signatures / passwords and also upgrade an account from an 'annotating user' to a fully licensed user (able to upload documents):
updateAccount.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user's account
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&sig=jill # (optional) The user's signature
&passwd=sesame # (optional) The user's new a.nnotate password
&licensed=1 # (optional) To upgrade to a licensed user
The return value is either "OK" or "ERR {error message}".
3. Login as a given user and display the given A.nnotate page
The loginAs.php call lets you create a link which logs a user in to their A.nnotate account and then displays either the notes / document index page or a particular document.
loginAs.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The user's account
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&loc=documents.php # The page to display after login
&errloc=http://mysite.org/error.php # An error page to display if login fails
&remember=1 # Store login info in browser cookie
Added Oct 2009:
&create=1 # (optional) Create user account if not present:
&sig=joe # (optional) - sig for new account if creating
&licensed=1 # (optional) - upgrade new account to licensed user
On visiting the link, the user will be logged in and redirected to the loc address. If there is a problem logging in, the link will redirect the user to the errloc url, with the msg parameter set, e.g. error.php?msg=some_error_msg.
The loc parameter determines the page which will be displayed on login. Suitable values are: documents.php for the list of documents, notes.php for the index of notes, pdfnotate.php?d=2008-01-01&c=abc123 for a particular document.
You may wish to post-date the request if including the loginAs.php link in a web page - simply increase the request time by the desired number of seconds you want the link to be valid for.
3.1 Creating new accounts on the fly if needed [new in v3.0.30, Oct 2009]
If you set the 'create=1' flag, then a new A.nnotate account will be created for the given annotateuser if they do not already have an account. You can also set the 'licensed=1' flag to enable the new account to upload documents. This is a shortcut which combines the standard calls to createAccount.php and updateAccount.php. This can be useful for integrations with external web applications - you can add a signed 'loginAs.php' link on your web application which creates an annotate user account and logs the user in. If the user already has an a.nnotate account, then the create=1 settings are ignored and it uses their existing account.
4. Uploading a document
The uploadDocument.php call lets you do a HTTP POST
to upload a document to the A.nnotate server and add it
to the given annotateuser's account. The URL should include
the normal GET parameters, with the other fields as
POST parameters. To post a file, use multipart/form-data
as with standard HTML form file uploads. The sample here is given
as an HTML form, but you can also simulate a form HTTP POST call from scripting languages,
or use a HTTP utility such as CURL.
<form method='POST' enctype='multipart/form-data' action='uploadDocument.php?
api-user=joe@example.com
&api-requesttime=123456
&api-annotateuser=jill@example.com
&api-auth=xyz1234543983jeflgnwefgdgd'>
<input name='desc'> # the description
<input name='tags'> # comma separated list of tags
# option 1: include a file browse component:
<input type='file' name='Filedata'>
# option 2: provide the URL of the document to fetch
<input name='url'>
<form>
You can either upload a file by posting it (a normal file upload), or by providing the URL of the document to fetch in the url parameter.
The default return value is "OK {document date} {document code}", or "ERR " + an error message, e.g.:
OK 2008-01-02 abc123
There are alternative return formats (see 4.1 and 4.2 below) which may be useful if you are running annotate on a different web server from your web application.
You can make a link to the uploaded document using a url like: pdfnotate.php?d=2008-01-02&c=abc123 - see also the previous section on the loginAs.php call which lets you
create a link to log in as a given user and display a document.
To control detailed settings of the displayed document, e.g. hiding particular buttons in the interface, opening on a particular page or note, or with a particular zoom level, please see the embedding a PDF guide.
4.1 Uploading a document and redirect to given page [new in v3.0.14]
Instead of returning a plain text string like "OK 2009-01-01 abc123" you can get uploadDocument.php to redirect to a user supplied URL, with the date and code as GET parameters. This can be useful if you need to store the uploaded date and code in your own database, and then show the document in an iframe.
<form method='POST' target='_blank' enctype='multipart/form-data' action='uploadDocument.php?
api-user=joe@example.com
&api-requesttime=123456
&api-annotateuser=jill@example.com
&api-auth=xyz1234543983jeflgnwefgdgd'>
<input type='hidden' name='fmt' value='redir' />
<input type='hidden' name='loc' value='http://yoursite.com/yourscript.php?arg123=abc' />
<input type='hidden' name='errloc' value='http://yoursite.com/yourerrscript.php?arg456=def' />
<input name='desc'> # the description
<input name='tags'> # comma separated list of tags
# option 1: include a file browse component:
<input type='file' name='Filedata'>
# option 2: provide the URL of the document to fetch
<input name='url'>
<form>
When the upload has completed, it will do a redirect to the url supplied in the loc post parameter, e.g.:
http://yoursite.com/yourscript.php?arg123=abc&d=2009-01-01&c=abc123&status=OK&annotateuser=jill@example.com -or- http://yoursite.com/yourerrscript.php?arg456=def&errmsg=...&status=ERR&annotateuser=jill@example.com
You can use the return values to show the document in an iframe. Note that the redirect is performed by uploadDocument.php generating a simple html web page which uses javascript to set document.location = ... It uses this technique in preference to a HTTP redirect as a work-around for Microsoft Internet Explorer's implementation of iframes.
4.2 Uploading a document and calling script in parent window [new in v3.0.14]
As another alternative callback mechanism, you can get uploadDocument.php to generate a javascript callback to your application, providing the document's date and code. Browsers typically allow iframes to call javascript methods in the parent window, even if the iframe is loaded from a different web server. If you have an iframe on your page with id iframeid, and javascript methods documentUploaded and uploadError on your page, you can add a form like:
<form method='POST' target='iframeid' enctype='multipart/form-data' action='uploadDocument.php?
api-user=joe@example.com
&api-requesttime=123456
&api-annotateuser=jill@example.com
&api-auth=xyz1234543983jeflgnwefgdgd'>
<input type='hidden' name='fmt' value='js' />
<input type='hidden' name='cb' value='parent.documentUploaded' />
<input type='hidden' name='errcb' value='parent.uploadError' />
<input name='desc'> # the description
<input name='tags'> # comma separated list of tags
# option 1: include a file browse component:
<input type='file' name='Filedata'>
# option 2: provide the URL of the document to fetch
<input name='url'>
<form>
When the upload has completed, it will call back one of the javascript functions you supply in the cb or errcb fields, e.g.
// Callbacks on finishing uploading.
function documentUploaded(date, code, user) {
alert('Document uploaded ok: ' + date + ' '+code+' '+user);
}
function uploadError(errmsg) {
alert('Document upload error: ' + errmsg);
}
5. Adding a note to a document using the API
The addNote.php call lets you add a note to a particular phrase of a document programmatically. It is also used for posting note edits, replies and deletions.
Request URL:
addNote.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The annotate user
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&d=2008-01-02 # The document upload date
&c=abc123 # the document code
HTTP POST parameters:
notetext # e.g. 'this is a note'
tags # e.g. 'person, important'
subject # the highlighted phrase
context # the sentence the note came from
type # 'note' or 'reply'
match # e.g. page-1:10:13 is a note on page 1 from word 10-13
state # 'live' or 'dead'
gid # leave empty for new note; set for edits / replies
signed # leave empty for default; can override user signature here
replyid # only needed for editing / deleting existing replies
linkTo # (optional) target URL if this is a note about a link
linkTitle # (optional) target URL title if this is a note about a link
The return value is "OK {note number}" or "ERR {error message}".
You might find it useful to try creating some notes using the normal a.nnotate gui, and fetching the list of notes using the calls in the api reference part 1 which also includes a more detailed explanation of the note parameters.
To edit a note, simply call addNote.php and set the gid field to be the same as the note you are editing. To reply to a note, again set the gid of the note, and set the type field to 'reply'. To delete a note, set the gid of the note and the state field to 'dead'.
To edit/delete a reply to a note, you need to know its replyid; this is the note number of the reply when first added, and is also set on loading the notes in the 'replyid' field. For new replies, leave the replyid parameter empty.
6. Editing a document's metadata and permissions
The updateDocumentMeta.php call lets you modify a document's metadata (title, tags, authors). It uses HTTP POST for the metadata; the document to use is specified by the date and code in the request URL:
Request URL:
updateDocumentMeta.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The annotate user
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&d=2008-01-02 # The document upload date
&c=abc123 # the document code
POST parameters:
title # Document title
authors # authors
notes # Notes on the document as a whole
tags # Document level tags
The return value is "OK" or "ERR {error message}". There are a number of optional POST parameters to the updateDocumentMeta.php call - these are described below. If the extra parameters are not included in the call, the settings will not be modified.
6.1 Advanced document metadata flags
There are a number of optional settings on a document, which can be used to control who is authorized to add comments, down to the level of individual pages.
Optional POST parameters for updateDocumentMeta.php:
defaultNoteStatus # shared / private / feedback
# The default setting for new notes.
allowNoteStatusChange # 1 / 0
# Whether to allow users to change the status.
allowNewNoteTags # 1 / 0
# Whether to allow users to add new tags.
closedForComments # 1 / 0
# If set, don't allow new comments
addToContacts # 1 / 0
# If set, add new document viewers to
# contacts list of doc owner
linkSharable # 1 / 0
# If set, enable access to document
# to anyone with a link [*added Dec 2009*]
6.2 Advanced document annotation permissions
It is also possible to control which users are permitted to annotate a document, and optionally set the allowed page ranges.
Optional POST parameters for updateDocMeta.php:
allowAnnotationUsers # comma or \n separated list of user emails
# e.g. for nobody except joe and jane:
# "_none,joe@example.com,jane@example.com"
denyAnnotationUsers # comma or \n separated list of user emails
# e.g. "badguy@example.com,badgal@example.com"
# Special values for entries in the allow / deny lists:
# "_any" --- any user with access to document
# "_none" --- no user
# the allow list is processed first, then deny.
# allow defaults to all users allowed, so to restrict to set users use
# "_none" first:
# e.g. allowAnnotationUsers : "_none, joe@example.com, jane@example.com"
#
To control whether particular users can annotate particular pages of a document, set the perPagePermissions list. The perPagePermissions list overrides the settings in the allowAnnotationUsers list, so just set one or the other, or the allow list will be ignored. The denyAnnotationUsers list can be used in conjunction with perPagePermissions though - it is checked afterwards and trumps the perPagePermissions settings to block particular users.
Optional POST parameters for updateDocMeta.php:
perPagePermissions # one entry per line, format as below:
# Format one entry per line, each entry is {user email}:{page range}\n
# Special values for the user field are:
# _any
# _none
# The page range is specified as a comma-separated list of
# page numbers; ranges like "10-20" can be included in the list.
# and an item can be prefixed by "!" to exclude that page.
# To match any page, use "1-".
# Note that the page numbers are those of the PDF file
# starting at 1 -
# If perPagePermissions is set, there is an implied: "_none:1-"
# rule preceeding any user rules.
# Example page ranges:
1,2,10-20 -- pages 1, 2 and 10-20 only
1-,!22 -- any page apart from 22
1-50,!10-20 -- equivalent to 1-9,21-50
50- -- pages 50 to the end of the document.
-20 -- all pages from start to #20
#
# Items are processed in the order of the entries.
# Example values for perPagePermissions array (NB there
# is a Colon (:) separator between the user name and the
# page range)
joe@example.com:12
jack@example.com:1-11,13-
jill@example.com:1-100,!33
Some examples:
# Only joe and jill allowed to annotate the document allowAnnotationUsers:"_none, joe@example.com, jill@example.com" denyAnnotationUsers: perPagePermissions: # Anyone apart from joe@example.com can annotate any page allowAnnotationUsers: denyAnnotationUsers:"joe@example.com" perPagePermissions: # joe can annotate all pages, other users only pp1-10, jack blocked: allowAnnotationUsers: denyAnnotationUsers:"jack@example.com" perPagePermissions:"_any:1-10\njoe@example.com:1-" # anyone can annotate all pages, but joe can't annotate page 22 perPagePermissions:"_any:1-\njoe@example.com:!22" # nobody can annotate any pages except joe who can annotate 1,3,5,7,9- perPagePermissions:"_none:1-\njoe@example.com:1,3,5,7,9-"
6.3 User defined document metadata fields [*new in v3.0.13 *]
You can store additional fields such as x_myfield in the document metadata object; any fields starting with x_ in the POST call to updateDocumentMeta.php will be stored in the metadata object.
Sample optional POST parameters for updateDocMeta.php for user defined fields: x_myfield: "some data item", x_mydatabaseid: "123456"
7. Deleting a document from a user's list
The deleteDocument.php call removes a document from the given user's list. If the given user is the owner of the document, it will also remove the document from all the other readers' lists. This call just uses HTTP GET:
deleteDocument.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The selected user
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&d=2008-01-02 # The document upload date
&c=abc123 # the document code
The return value is "OK" or "ERR {message}".
8. Adding a document to a given user's list
The authorizeReader.php call adds a document to the given user's list.
authorizeReader.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=jill@example.com # The annotate user
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
&d=2008-01-02 # The document upload date
&c=abc123 # the document code
The return value is "OK" or "ERR {message}".
9. Listing user accounts
The listUsers.php call lists the a.nnotate users on the server administered by the given api-annotateuser:
listUsers.php?
api-user=joe@example.com # The admin user for the account
&api-requesttime=123456 # the Unix timestamp (GMT)
&api-annotateuser=joe@example.com # Set this to the api-user
&api-auth=xyz1234543983jeflgnwefgdgd # The signed hash code.
The response is "ERR {error message}" or a JSON string with two arrays; "members" lists email addresses of group members, and "annotators" lists email addresses of unlicensed users, e.g.:
{
members : ["joe@example.com","jill@example.com"],
annotators : [ "other@example.com" ]
}