Recent changes to PublicationAPI

PublicationAPI modified by Domhnall101

Domhnall101 — Tue, 06 Oct 2015 20:01:04 -0000

--- v16
+++ v17
@@ -1,10 +1,11 @@
 Draft 2015-06-22
+##Publication API

-## 1. Publications ##
+### 1. Publications ##

 Publications are created by POSTing JSON data to the `/publications` endpoint.  Information about a particular publication can be retrieved by a GET request to `/publication/`*pubID*.

-### Add new publication ###
+#### Add new publication ###
 Endpoint: /publications
 Method: POST
 Request body: { "title":"*title*", "edition":*edID*, "type":*type* }
@@ -14,7 +15,7 @@
 Comments:
 The "type" field should be one of "PDF", "TEI", "DYNAMIC", "OAC", or "XML".  The publication's "creator" field will be set to the user who made the POST.  The "creation" and "modification" fields will be set to the current time.

-### List publications ###
+#### List publications ###
 Endpoint: /publications
 Method: GET
 Request body: none
@@ -23,7 +24,7 @@
 Comments:
 The endpoint returns the IDs and titles of all publications for which the user has `VIEWER` permissions or better.  If the `public=true` parameter is passed to the endpoint, it will instead list all publications for which the public user (i.e. user 0) has `VIEWER` permissions.

-### Get publication details ###
+#### Get publication details ###
 Endpoint: /publication/*pubID*
 Method: GET
 Request body: none
@@ -31,28 +32,28 @@
 Status: 200 on success, 404 if *pubID* doesn't exist
 Comments: The returned [Publication](Publication API Structures#publication) object will include an array of [Permission](Edition API Structures#permission) objects and an array of [Section](Edition API Structures#section) IDs.

-### Set publication details ###
+#### Set publication details ###
 Endpoint: /publication/*pubID*
 Method: PUT
 Request body: a [Publication](Publication API Structures#publication) object
 Response body: none
 Status: 204 on success, 404 if *pubID* doesn't exist

-### Delete a publication ###
+#### Delete a publication ###
 Endpoint: /publication/*pubID*
 Method: DELETE
 Request body: none
 Status: 204 on success, 404 if *pubID* doesn't exist
 Comments: Also deletes all associated Sections and their Rules.

-### Set publication permissions ###
+#### Set publication permissions ###
 Endpoint: /publication/*pubID*/permissions
 Method: PUT
 Request body: an array of [Permission](Edition API Structures#permission) objects
 Response body: none
 Status: 204 on success, 404 if *pubID* doesn't exist

-### Set publication sections ###
+#### Set publication sections ###
 Endpoint: /publication/*pubID*/sections
 Method: PUT
 Request body: an array of [Section](Edition API Structures#section) objects
@@ -60,9 +61,9 @@
 Status: 204 on success, 404 if *pubID* doesn't exist

-## 2. Sections ##
+### 2. Sections ##

-### Add new section to a publication ###
+#### Add new section to a publication ###
 Endpoint: /publication/*pubID*/sections
 Method: POST
 Request body: \{
@@ -78,22 +79,22 @@
 Response body: none
 Status: 201 on success, 409 if *title* is already being used in this publication.

-### Set Section details ###
+#### Set Section details ###
 Endpoint: /section/*sectID*
 Method: PUT
 Request body: [Section](Publication API Structures#section) object
 Status: 204 on success, 404 if *sectID* doesn't exist

-### Delete a Section ###
+#### Delete a Section ###
 Endpoint: /section/*sectID*
 Method: DELETE
 Status: 204 on success, 404 if *sectID* doesn't exist
 Comment: Also deletes all associated Rules.

-## 3. Generating PDFs ##
+### 3. Generating PDFs ##

-### Create a PDF ###
+#### Create a PDF ###
 Endpoint: /pdfs
 Method: POST
 Request body: XHTML+CSS to be converted into a PDF
@@ -102,7 +103,7 @@
 Status: 201 on success
 Comment: Uses the supplied XHTML+CSS to generate a PDF document.  The document will be stored in the database and can be retrieved using the location returned in the response headers.

-### Get a PDF ###
+#### Get a PDF ###
 Endpoint: /pdf/*pdfIDs*
 Method: GET
 Response body: PDF data for the given document

Publication API modified by Eric Smith

Eric Smith — Mon, 22 Jun 2015 22:48:44 -0000

--- v15
+++ v16
@@ -1,4 +1,4 @@
-Draft 2015-06-15
+Draft 2015-06-22

 ## 1. Publications ##

@@ -19,8 +19,9 @@
 Method: GET
 Request body: none
 Response body: \[{"id":pubID₁, "title":"title₁"}, … ]
+Request parameters: `public=true` (optional)
 Comments:
-The endpoint returns the IDs and titles of all publications for which the user has `VIEWER` permissions or better.
+The endpoint returns the IDs and titles of all publications for which the user has `VIEWER` permissions or better.  If the `public=true` parameter is passed to the endpoint, it will instead list all publications for which the public user (i.e. user 0) has `VIEWER` permissions.

 ### Get publication details ###
 Endpoint: /publication/*pubID*

Publication API modified by Eric Smith

Eric Smith — Mon, 15 Jun 2015 19:06:47 -0000

--- v14
+++ v15
@@ -1,4 +1,4 @@
-Draft 2014-11-19
+Draft 2015-06-15

 ## 1. Publications ##

@@ -90,3 +90,19 @@
 Comment: Also deletes all associated Rules.

+## 3. Generating PDFs ##
+
+### Create a PDF ###
+Endpoint: /pdfs
+Method: POST
+Request body: XHTML+CSS to be converted into a PDF
+Response location: /pdf/*pdfID*
+Response body: none
+Status: 201 on success
+Comment: Uses the supplied XHTML+CSS to generate a PDF document.  The document will be stored in the database and can be retrieved using the location returned in the response headers.
+
+### Get a PDF ###
+Endpoint: /pdf/*pdfIDs*
+Method: GET
+Response body: PDF data for the given document
+Comment: Returns a previously-generated PDF document.

Publication API modified by Eric Smith

Eric Smith — Wed, 29 Apr 2015 19:50:50 -0000

--- v13
+++ v14
@@ -13,6 +13,14 @@
 Status: 201 on success, 409 if *title* already in use.
 Comments:
 The "type" field should be one of "PDF", "TEI", "DYNAMIC", "OAC", or "XML".  The publication's "creator" field will be set to the user who made the POST.  The "creation" and "modification" fields will be set to the current time.
+
+### List publications ###
+Endpoint: /publications
+Method: GET
+Request body: none
+Response body: \[{"id":pubID₁, "title":"title₁"}, … ]
+Comments:
+The endpoint returns the IDs and titles of all publications for which the user has `VIEWER` permissions or better.

 ### Get publication details ###
 Endpoint: /publication/*pubID*

Publication API modified by Eric Smith

Eric Smith — Wed, 19 Nov 2014 18:12:47 -0000

--- v12
+++ v13
@@ -12,7 +12,7 @@
 Response body: none
 Status: 201 on success, 409 if *title* already in use.
 Comments:
-The *type* should be one of "PDF", "TEI", "DYNAMIC", "OAC", or "XML".  The publication's "creator" field will be set to the user who made the POST.  The "creation" and "modification" fields will be set to the current time.
+The "type" field should be one of "PDF", "TEI", "DYNAMIC", "OAC", or "XML".  The publication's "creator" field will be set to the user who made the POST.  The "creation" and "modification" fields will be set to the current time.

 ### Get publication details ###
 Endpoint: /publication/*pubID*

Publication API modified by Eric Smith

Eric Smith — Wed, 19 Nov 2014 18:12:25 -0000

--- v11
+++ v12
@@ -1,4 +1,4 @@
-Draft 2014-11-05
+Draft 2014-11-19

 ## 1. Publications ##

@@ -7,12 +7,12 @@
 ### Add new publication ###
 Endpoint: /publications
 Method: POST
-Request body: { "title" : "*title*", "edition" : *edID* }
+Request body: { "title":"*title*", "edition":*edID*, "type":*type* }
 Response location: /publication/*pubID*
 Response body: none
 Status: 201 on success, 409 if *title* already in use.
 Comments:
-The publication's "creator" field will be set to the user who made the POST.  The "creation" and "modification" fields will be set to the current time.
+The *type* should be one of "PDF", "TEI", "DYNAMIC", "OAC", or "XML".  The publication's "creator" field will be set to the user who made the POST.  The "creation" and "modification" fields will be set to the current time.

 ### Get publication details ###
 Endpoint: /publication/*pubID*

Publication API modified by Eric Smith

Eric Smith — Thu, 06 Nov 2014 18:52:42 -0000

--- v10
+++ v11
@@ -28,6 +28,13 @@
 Request body: a [Publication](Publication API Structures#publication) object
 Response body: none
 Status: 204 on success, 404 if *pubID* doesn't exist
+
+### Delete a publication ###
+Endpoint: /publication/*pubID*
+Method: DELETE
+Request body: none
+Status: 204 on success, 404 if *pubID* doesn't exist
+Comments: Also deletes all associated Sections and their Rules.

 ### Set publication permissions ###
 Endpoint: /publication/*pubID*/permissions
@@ -72,5 +79,6 @@
 Endpoint: /section/*sectID*
 Method: DELETE
 Status: 204 on success, 404 if *sectID* doesn't exist
+Comment: Also deletes all associated Rules.

Publication API modified by Eric Smith

Eric Smith — Wed, 05 Nov 2014 23:59:14 -0000

--- v9
+++ v10
@@ -1,4 +1,4 @@
-Draft 2014-10-30
+Draft 2014-11-05

 ## 1. Publications ##

@@ -20,6 +20,7 @@
 Request body: none
 Response body: a [Publication](Publication API Structures#publication) object
 Status: 200 on success, 404 if *pubID* doesn't exist
+Comments: The returned [Publication](Publication API Structures#publication) object will include an array of [Permission](Edition API Structures#permission) objects and an array of [Section](Edition API Structures#section) IDs.

 ### Set publication details ###
 Endpoint: /publication/*pubID*
@@ -27,13 +28,6 @@
 Request body: a [Publication](Publication API Structures#publication) object
 Response body: none
 Status: 204 on success, 404 if *pubID* doesn't exist
-
-### Get publication permissions ###
-Endpoint: /publication/*pubID*/permissions
-Method: GET
-Request body: none
-Response body: an array of [Permission](Edition API Structures#permission) object
-Status: 200 on success, 404 if *pubID* doesn't exist

 ### Set publication permissions ###
 Endpoint: /publication/*pubID*/permissions

Publication API modified by Eric Smith

Eric Smith — Fri, 31 Oct 2014 21:47:17 -0000

--- v8
+++ v9
@@ -74,3 +74,9 @@
 Request body: [Section](Publication API Structures#section) object
 Status: 204 on success, 404 if *sectID* doesn't exist

+### Delete a Section ###
+Endpoint: /section/*sectID*
+Method: DELETE
+Status: 204 on success, 404 if *sectID* doesn't exist
+
+

Publication API modified by Eric Smith

Eric Smith — Thu, 30 Oct 2014 16:24:19 -0000

--- v7
+++ v8
@@ -1,8 +1,8 @@
-Draft 2014-10-28
+Draft 2014-10-30

 ## 1. Publications ##

-Publications are created by POSTing JSON data to the /publications endpoint.  Information about a particular publication can be retrieved by a GET request to /publication/*pubID*.
+Publications are created by POSTing JSON data to the `/publications` endpoint.  Information about a particular publication can be retrieved by a GET request to `/publication/`*pubID*.

 ### Add new publication ###
 Endpoint: /publications
@@ -42,13 +42,6 @@
 Response body: none
 Status: 204 on success, 404 if *pubID* doesn't exist

-### Get publication sections ###
-Endpoint: /publication/*pubID*/sections
-Method: GET
-Request body: none
-Response body: array of [Section](Publication API Structures#section) objects
-Status: 200 on success, 404 if *pubID* doesn't exist
-
 ### Set publication sections ###
 Endpoint: /publication/*pubID*/sections
 Method: PUT