PublicationAPI

Draft 2015-06-22

Publication API

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

Endpoint: /publications
Method: POST
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 "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₁"}, … ]
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. 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
Method: GET
Request body: none
Response body: a Publication object
Status: 200 on success, 404 if pubID doesn't exist
Comments: The returned Publication object will include an array of Permission objects and an array of Section IDs.

Set publication details

Endpoint: /publication/pubID
Method: PUT
Request body: a 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
Method: PUT
Request body: an array of Permission objects
Response body: none
Status: 204 on success, 404 if pubID doesn't exist

Set publication sections

Endpoint: /publication/pubID/sections
Method: PUT
Request body: an array of Section objects
Response body: none
Status: 204 on success, 404 if pubID doesn't exist

2. Sections

Add new section to a publication

Endpoint: /publication/pubID/sections
Method: POST
Request body: {
   "publication": pubID,
   "title": "title",
   "type": "TEXT"|"ENDNOTE"|"FOOTNOTE"|"INDEX"|"TABLE_OF_CONTENTS",
   "decoration": array of Rule objects
   "layout": array of Rule objects
   "outlines": array of Outline IDs
   "template": "HTML template"
}
Response location: /section/sectID
Response body: none
Status: 201 on success, 409 if title is already being used in this publication.

Set Section details

Endpoint: /section/sectID
Method: PUT
Request body: 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
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.