CoreAPI

Draft 2015-06-16

Core API

1. Users

Users are created by POSTing JSON data to the /users endpoint. Information about a particular user can be retrieved by a get request to /user/userID.

Add new user

Endpoint: /users
Method: POST
Request content-type: application/json
Request body: { "mail" : "emailAddress", "name" : "fullName", "password" : "password" }
Response location: /user/userID
Response body: none
Status: 201 on success, 409 if email address already in use.
Comments:
The newly-registered user will be sent an email, which requires them to click a link to confirm their registration. The user's creation and last_login fields will be set to the current time.

Invite new user to edition

Endpoint: /users
Method: POST
Request content-type: application/json
Request body: { "mail" : "emailAddress", "name" : "fullName", "edition" : edID }
Response location: /user/userID
Response body: none
Status: 201 on success, 409 if email address already in use.
Comments:
The invitee will receive an email indicating that they have been invited by the current user (i.e. the one whose session invoked the endpoint) to work on the given edition. The email provides a temporary randomly-generated password, as well as a link which has to be clicked to activate the new account. The new user's creation field will be set to the current time, but their last_login field will be left as NULL. The new user will be granted CONTRIBUTOR access to the edition; it is up to the edition's owner to upgrade their access if so desired.

Invite new user to publication

Endpoint: /users
Method: POST
Request content-type: application/json
Request body: { "mail" : "emailAddress", "name" : "fullName", "publication" : pubID }
Response location: /user/userID
Response body: none
Status: 201 on success, 409 if email address already in use.
Comments:
The invitee will receive an email indicating that they have been invited by the current user (i.e. the one whose session invoked the endpoint) to work on the given publication. The email provides a temporary randomly-generated password, as well as a link which has to be clicked to activate the new account. The new user's creation field will be set to the current time, but their last_login field will be left as NULL. The new user will be granted CONTRIBUTOR access to the publication; it is up to the publication's owner to upgrade their access if so desired.

Invite new anonymous user to publication

Endpoint: /users
Method: POST
Request content-type: application/json
Request body: { "mail" : "emailAddress", "publication" : pubID }
Response location: /user/userID
Response body: none
Status: 201 on success.
Comments:
The invitee will receive an email indicating that they have been invited by the current user (i.e. the one whose session invoked the endpoint) to work on the given publication. The email provides a randomly-generated user-name (which will also double as a password), as well as a link to the review page for the given publication. Unlike ordinary users, newly-created anonymous users do not have to visit the confirmation page. Once the invitation email has been sent, the email address is not stored anywhere by Tradamus. The new user's creation field will be set to the current time, but their last_login field will be left as NULL. The new user will be granted CONTRIBUTOR access to the publication.

Get user details

Endpoint: /user/userID
Method: GET
Request body: none
Response content-type: application/json
Response body: {"id":1,"mail":"ericsmith@slu.edu","name":"Eric Smith","disabled":false,"creation":1372884249000,"lastLogin":1372885349000}
Status: 200 on success, 401 if not logged in, 404 if user not found.
Comments:
Returns a JSON object providing details about the requested user.

Get user details by email

Endpoint: /user?mail=emailAddress
Method: GET
Request body: none
Response content-type: application/json
Response body: {"id":1,"mail":"ericsmith@slu.edu","name":"Eric Smith","disabled":false,"creation":1372884249000,"lastLogin":1372885349000}
Response location: /user/userID
Status: 200 on success, 401 if not logged in, 404 if user not found.
Comments:
Returns a JSON object providing details about the requested user.

Modify user details

Endpoint: /user/userID
Method: PUT
Request content-type: application/json
Request body (all fields optional) { "mail" : "emailAddress", "name" : "fullName", "password" : "password" }
Response body: none
Status: 204 on success, 401 if not logged in, 403 if you try to modify another user.
Comments:
Any fields which are specified in the request body will be set to the supplied values. Fields which are omitted will be unchanged.

Reset user password

Endpoint: /user?reset=emailAddress
Method: PUT
Request content-type: n/a
Request body: none
Response body: none
Status: 204 on success, 404 if emailAddress is not found.
Comments:
A new random password will be generated and emailed to the user.

Ask to resend confirmation email

Endpoint: /user?resend=emailAddress
Method: PUT
Request content-type: n/a
Request body: none
Response body: none
Status: 204 on success, 404 if emailAddress is not found, 410 if emailAddress has already been confirmed.
Comments:
The confirmation email will be resent to the given email.

2. Login

Log in to Tradamus

Endpoint: /login
Method: POST
Request content-type: application/json
Request body: { "mail" : "emailAddress", "password" : "password" }
Response location: /user/userID
Response body: none
Response cookies: JSESSIONID=sessionID; Path=/Tradamus/; HttpOnly
Status: 204 on success, 401 on invalid login.

Log out of Tradamus

Endpoint: /login
Method: POST
Request content-type: n/a
Request body: must be empty
Response body: none
Response cookies: JSESSIONID=sessionID; Path=/Tradamus/; HttpOnly
Status: 204 on success.

Check login status

Endpoint: /login
Method: GET
Request body: none
Response content-type: application/json
Response body: { "id":userID, "mail":"emailAddress","name":"fullName","disabled":false,"creation":creationTime,"lastLogin":lastLoginTime }
Status: 200 if JSESSIONID is valid, 401 if it's not.

3. Config

Endpoint: /config
Method: GET
Request body: none
Response content-type: application/json
Response body: {"version":"0.9.1", "revision":189}
Status: 200 on success.
Comments: The response's "version" property contains the "version-num" property from build.xml. The "revision" property contains the SVN revision which was used to build the WAR file. At present, this endpoint does not require authentication.

4. Activity Log

Endpoint: /activity
Method: GET
Parameters: user=userID to retrieve activities of a given user
table=table&id=id to retrieve activities associated with a given entity. The table parameter can be one of annotations, canvasses, editions, images, manifests, outlines, pages, transcriptions, users, or witnesses. The optional id parameter identifies the particular entity of that type.
limit=limit to limit the number of records returned
Request body: none
Response body: An array of activity records:
[
   {
      "content":"Lectio 1, Prologus [Reims Transcription]",
      "operation":"INSERT",
      "time":1381535382000,
      "entity":"witness/1",
      "parent":"edition/1",
      "user":2
   },
   …
]
Status: 200 on success
Comments: The endpoint returns an array of activity entries. The operation property can be INSERT, UPDATE, DELETE, or VIEW. The entity which changed is identified by the entity property. The time of the activity and the user responsible are specified by the time and user properties. For insertions, there will also be a parent property which identifies where the newly-created entity was inserted.

The content property describes the change that occurred. The values are summarised in this table:

operation	type	content
INSERT	editions	Title of newly-created edition
UPDATE	editions	JSON object containing changes sent by the client For /editions sub-endpoints, it may be a JSON array of motes, or permissions.
INSERT	users	Name of newly-created user
UPDATE	users	"Account confirmed."
INSERT	witnesses	Title of newly-created witness
UPDATE	witnesses	"Witness updated."
UPDATE	other	JSON object containing changes sent by the client
DELETE	all	none

5. Deferred Results

Certain endpoints which invoke long-running processes (currently collation and generation of PDFs) have the option of producing deferred results. The endpoint will return immediately with a 303 "See Other" result and a location header which points to the /deliverable endpoint along with a particular deliverable ID.

Endpoint: /deliverable/delID
Method: GET
Parameters: none
Request body: none
Response content-type: application/json for deferred collation, application/pdf for PDF generation
Response body: results of the long-running process