/texts/<object_id>/¶

The /texts/<object_id>/ endpoint interacts with a specific literary work in Tesserae’s database.

Note that <object_id> is a placeholder to be replaced by an identifier refering to a specific text (i.e., literary work). Throughout the rest of this page, <object_id> will continue to serve as a placeholder for a text’s identifier.

GET¶

Requesting GET at /texts/<object_id>/ provides information on the literary work specified by <object_id>.

Request¶

Note that an <object_id> used for one text on the Tesserae website may be different from the <object_id> used to refer to the same text on a different instance of Tesserae (such as one locally installed on your computer).

Response¶

On success, the response includes a data payload consisting of a JSON object with the following keys:

Key	Value
"author"	A string identifying the text’s author.
"object_id"	A string which uniquely identifies the text on the instance of Tesserae you queried.
"language"	A string identifying the composition language of the text.
"title"	A string identifying the text’s name.
"year"	An integer representing the text’s publication year; a negative integer corresponds to the BC era.

On failure, the data payload contains error information in a JSON object with the following keys:

Key	Value
"object_id"	A string corresponding to <object_id>.
"message"	A string explaining why the request data payload was rejected.

Examples¶

Retrieve a Text’s Database Entry¶

Suppose that 5c6c69f042facf59122418f6 is the identifier associated with Lucan’s Bellum Civile.

Request:

curl -i -X GET "https://tesserae.caset.buffalo.edu/api/texts/5c6c69f042facf59122418f6/"

Response:

HTTP/1.1 200 OK
...

{
  "author": "lucan",
  "object_id": "5c6c69f042facf59122418f6",
  "path": "https://raw.githubusercontent.com/tesserae/tesserae/master/texts/la/lucan.bellum_civile.tess",
  "language": "latin",
  "title": "bellum civile",
  "year": 65
}

Attempt to Retrieve a Database Entry with a Malformed object_id¶

Request:

curl -i -X GET "https://tesserae.caset.buffalo.edu/api/texts/badid/"

Response:

HTTP/1.1 400 Bad Request
...

{
  "object_id": "badid",
  "message": "Provided identifier (badid) is malformed."
}

Attempt to Retrieve the Database Entry for a Text Not in the Database¶

Assume that no text in the database has the identifier “DEADBEEFDEADBEEFDEADBEEF”.

Request:

curl -i -X GET "https://tesserae.caset.buffalo.edu/api/texts/DEADBEEFDEADBEEFDEADBEEF/"

Response:

HTTP/1.1 404 Not Found
...

{
  "object_id": "DEADBEEF",
  "message": "No text with the provided identifier (DEADBEEFDEADBEEFDEADBEEF) was found in the database."
}

PATCH¶

NB: The PATCH method for /texts/<object_id>/ is available only on the administrative server

Requesting PATCH at /texts/<object_id>/ with an appropriate JSON data payload will update the database entry of the text with an identifier of <object_id>. The update will be in accordance with the JSON data.

Request¶

Appropriate JSON data for a PATCH at /texts/<object_id>/ is any JSON object without the following keys: "object_id", "id", "_id", "path", "divisions". The keys in this object specify which attributes of the text entry in Tesserae’s database will be updated (or added, if the key does not correspond with any of the text entry’s attributes). The new values of these attributes are specified by the values of the keys corresponding to those attributes.

NB: You cannot update a text’s identifier.

Response¶

On success, the data payload contains the text entry in Tesserae’s database after the update has been made.

On failure, the data payload contains error information in a JSON object with the following keys:

Key	Value
"object_id"	A string matching <object_id>.
"data"	The JSON object received as request data payload.
"message"	A string explaining why the request data payload was rejected.

Examples¶

Update the Value of a Pre-existing Attribute of a Text’s Database Entry¶

Assume that the following entry exists in the database:

{
  "author": "lucan",
  "object_id": "5c6c69f042facf59122418f6",
  "path": "https://raw.githubusercontent.com/tesserae/tesserae/master/texts/la/lucan.bellum_civile.tess",
  "language": "latin",
  "title": "bellum civile",
  "year": 65
}

Request:

curl -i -X PATCH "https://tesserae.caset.buffalo.edu/api/texts/5c6c69f042facf59122418f6/" -d '{ \
  "title": "Pharsalia" \
}'

Response:

HTTP/1.1 200 OK
...

{
  "author": "lucan",
  "object_id": "5c6c69f042facf59122418f6",
  "path": "https://raw.githubusercontent.com/tesserae/tesserae/master/texts/la/lucan.bellum_civile.tess",
  "language": "latin",
  "title": "Pharsalia",
  "year": 65
}

Add New User-Specified Information to a Text’s Database Entry¶

Assume that the following entry exists in the database:

{
  "author": "lucan",
  "object_id": "5c6c69f042facf59122418f6",
  "path": "https://raw.githubusercontent.com/tesserae/tesserae/master/texts/la/lucan.bellum_civile.tess",
  "language": "latin",
  "title": "bellum civile",
  "year": 65
}

Request:

curl -i -X PATCH "https://tesserae.caset.buffalo.edu/api/texts/5c6c69f042facf59122418f6/" -d '{ \
  "alternate_title": "Pharsalia" \
}'

Response:

HTTP/1.1 200 OK
...

{
  "author": "lucan",
  "object_id": "5c6c69f042facf59122418f6",
  "alternate_title": "Pharsalia"
  "path": "https://raw.githubusercontent.com/tesserae/tesserae/master/texts/la/lucan.bellum_civile.tess",
  "language": "latin",
  "title": "bellum civile",
  "year": 65
}

Attempt to Update a Database Entry with a Malformed object_id¶

Request:

curl -i -X PATCH "https://tesserae.caset.buffalo.edu/api/texts/badid/" -d '{ \
  "fail": "this example will" \
}'

Response:

HTTP/1.1 400 Bad Request
...

{
  "object_id": "badid",
  "data": {
    "fail": "this example will"
  },
  "message": "Provided identifier (badid) is malformed."
}

Attempt to Update the Database Entry for a Text Not in the Database¶

Assume that no text in the database has the identifier “DEADBEEFDEADBEEFDEADBEEF”.

Request:

curl -i -X PATCH "https://tesserae.caset.buffalo.edu/api/texts/DEADBEEFDEADBEEFDEADBEEF/" -d '{ \
  "fail": "this example will" \
}'

Response:

HTTP/1.1 404 Not Found
...

{
  "object_id": "DEADBEEFDEADBEEFDEADBEEF",
  "data": {
    "fail": "this example will"
  },
  "message": "No text with the provided identifier (DEADBEEFDEADBEEFDEADBEEF) was found in the database."
}

DELETE¶

NB: The DELETE method for /texts/<object_id>/ is available only on the administrative server

Requesting DELETE at /texts/<object_id>/ will delete the text identified by <object_id> from Tesserae’s database.

Request¶

There is no request data payload.

Response¶

On success, there is no response data payload.

On failure, the data payload contains error information in a JSON object with the following keys:

Key	Value
"object_id"	A string matching <object_id>.
"message"	A string explaining why the request data payload was rejected.

Examples¶

Delete a Text¶

Assume that the following entry exists in the database:

{
  "author": "lucan",
  "object_id": "5c6c69f042facf59122418f6",
  "path": "https://raw.githubusercontent.com/tesserae/tesserae/master/texts/la/lucan.bellum_civile.tess",
  "language": "latin",
  "title": "bellum civile",
  "year": 65
}

Request:

curl -i -X DELETE "https://tesserae.caset.buffalo.edu/api/texts/5c6c69f042facf59122418f6/"'

Response:

HTTP/1.1 204 No Content
...

Attempt to Delete a Database Entry with a Malformed object_id¶

Request:

curl -i -X DELETE "https://tesserae.caset.buffalo.edu/api/texts/badid/"

Response:

HTTP/1.1 400 Bad Request
...

{
  "object_id": "badid"
  "message": "Provided identifier (badid) is malformed."
}

Attempt to Delete a Database Entry for a Text Not in the Database¶

Assume that no text in the database has the identifier “DEADBEEFDEADBEEFDEADBEEF”.

Request:

curl -i -X DELETE "https://tesserae.caset.buffalo.edu/api/texts/DEADBEEFDEADBEEFDEADBEEF/"

Response:

HTTP/1.1 404 Not Found
...

{
  "object_id": "DEADBEEFDEADBEEFDEADBEEF"
  "message": "No text with the provided identifier (DEADBEEFDEADBEEFDEADBEEF) was found in the database."
}