Recent changes to CoreAPI

CoreAPI modified by Domhnall101

Domhnall101 — Tue, 06 Oct 2015 19:32:25 -0000

--- v7
+++ v8
@@ -1,10 +1,11 @@
 Draft 2015-06-16
+#Core API

-## 1. Users ##
+### 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 ###
+#### Add new user ###
 Endpoint: /users
 Method: POST
 Request content-type: application/json
@@ -15,7 +16,7 @@
 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 ###
+#### Invite new user to edition ###
 Endpoint: /users
 Method: POST
 Request content-type: application/json
@@ -26,7 +27,7 @@
 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 ###
+#### Invite new user to publication ###
 Endpoint: /users
 Method: POST
 Request content-type: application/json
@@ -37,7 +38,7 @@
 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 ###
+#### Invite new anonymous user to publication ###
 Endpoint: /users
 Method: POST
 Request content-type: application/json
@@ -48,7 +49,7 @@
 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 ###
+#### Get user details ####
 Endpoint: /user/*userID*
 Method: GET
 Request body: none
@@ -58,7 +59,7 @@
 Comments:
 Returns a JSON object providing details about the requested user.

-### Get user details by email ###
+#### Get user details by email ###
 Endpoint: /user?mail=*emailAddress*
 Method: GET
 Request body: none
@@ -69,7 +70,7 @@
 Comments:
 Returns a JSON object providing details about the requested user.

-### Modify user details ###
+#### Modify user details ###
 Endpoint: /user/*userID*
 Method: PUT
 Request content-type: application/json
@@ -79,7 +80,7 @@
 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 ###
+#### Reset user password ###
 Endpoint: /user?reset=*emailAddress*
 Method: PUT
 Request content-type: n/a
@@ -90,7 +91,7 @@
 A new random password will be generated and emailed to the user.

-### Ask to resend confirmation email ###
+#### Ask to resend confirmation email ###
 Endpoint: /user?resend=*emailAddress*
 Method: PUT
 Request content-type: n/a
@@ -101,9 +102,9 @@
 The confirmation email will be resent to the given email.

-## 2. Login ##
+### 2. Login ##

-### Log in to Tradamus ###
+#### Log in to Tradamus ###
 Endpoint: /login
 Method: POST
 Request content-type: application/json
@@ -113,7 +114,7 @@
 Response cookies: JSESSIONID=*sessionID*; Path=/Tradamus/; HttpOnly
 Status:  204 on success, 401 on invalid login.

-### Log out of Tradamus ###
+#### Log out of Tradamus ###
 Endpoint: /login
 Method: POST
 Request content-type: n/a
@@ -122,7 +123,7 @@
 Response cookies: JSESSIONID=*sessionID*; Path=/Tradamus/; HttpOnly
 Status:  204 on success.

-### Check login status ###
+#### Check login status ###
 Endpoint: /login
 Method: GET
 Request body: none
@@ -131,7 +132,7 @@
 Status: 200 if JSESSIONID is valid, 401 if it's not.

-## 3. Config ##
+### 3. Config ##
 Endpoint:  /config
 Method:  GET
 Request body:  none
@@ -141,7 +142,7 @@
 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 ##
+### 4. Activity Log ##

 Endpoint:  /activity
 Method:  GET
@@ -178,7 +179,7 @@
 DELETE    | *all*     | none

-## 5. Deferred Results ##
+### 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.

Core API modified by Eric Smith

Eric Smith — Tue, 16 Jun 2015 22:07:31 -0000

--- v6
+++ v7
@@ -1,4 +1,4 @@
-Draft 2015-06-04
+Draft 2015-06-16

 ## 1. Users ##

@@ -178,3 +178,13 @@
 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

Core API modified by Eric Smith

Eric Smith — Thu, 04 Jun 2015 16:41:32 -0000

--- v5
+++ v6
@@ -1,4 +1,4 @@
-Draft 2015-06-03
+Draft 2015-06-04

 ## 1. Users ##

@@ -46,7 +46,7 @@
 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 which has to be clicked to activate the new account.  Once the 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.
+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*

Core API modified by Eric Smith

Eric Smith — Wed, 03 Jun 2015 21:42:14 -0000

--- v4
+++ v5
@@ -41,12 +41,12 @@
 Endpoint: /users
 Method: POST
 Request content-type: application/json
-Request body: { "mail" : "*emailAddress*", "publication" : *pubID*, "editor" : *true|false* }
+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 and a temporary randomly-generated password, as well as a link which has to be clicked to activate the new account.  Once the 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.  If the `editor` field is true, the new user will be granted `REVIEW_EDITOR` access to the publication, giving them the ability to invite new reviewers, but not to make annotations on the publications.  If the `editor` field is false, the new user will be granted `CONTRIBUTOR` access to the publication.
+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 which has to be clicked to activate the new account.  Once the 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*

Core API modified by Eric Smith

Eric Smith — Wed, 03 Jun 2015 16:26:48 -0000

--- v3
+++ v4
@@ -1,4 +1,4 @@
-Draft 2015-05-27
+Draft 2015-06-03

 ## 1. Users ##

@@ -41,7 +41,7 @@
 Endpoint: /users
 Method: POST
 Request content-type: application/json
-Request body: { "mail" : "*emailAddress*", "publication" : *pubID*, "editor" : true|false }
+Request body: { "mail" : "*emailAddress*", "publication" : *pubID*, "editor" : *true|false* }
 Response location: /user/*userID*
 Response body: none
 Status: 201 on success.

Core API modified by Eric Smith

Eric Smith — Wed, 03 Jun 2015 16:25:37 -0000

--- v2
+++ v3
@@ -15,16 +15,38 @@
 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 ###
+### Invite new user to edition ###
 Endpoint: /users
 Method: POST
 Request content-type: application/json
-Request body: { "mail" : "*emailAddress*", "name" : "*fullName*", "edition" : *editionID* }
+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*, "editor" : true|false }
+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 and a temporary randomly-generated password, as well as a link which has to be clicked to activate the new account.  Once the 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.  If the `editor` field is true, the new user will be granted `REVIEW_EDITOR` access to the publication, giving them the ability to invite new reviewers, but not to make annotations on the publications.  If the `editor` field is false, the new user will be granted `CONTRIBUTOR` access to the publication.

 ### Get user details ###
 Endpoint: /user/*userID*

Core API modified by Eric Smith

Eric Smith — Wed, 27 May 2015 22:36:50 -0000

--- v1
+++ v2
@@ -1,3 +1,5 @@
+Draft 2015-05-27
+
 ## 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*.
@@ -105,3 +107,52 @@
 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
+
+

Core API modified by Eric Smith

Eric Smith — Wed, 27 May 2015 22:34:06 -0000

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

Endpoint: /users
Method: POST
Request content-type: application/json
Request body: { "mail" : "emailAddress", "name" : "fullName", "edition" : editionID }
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.

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.

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.

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.