/texts/

The /texts/ endpoint interacts with Tesserae’s database of literary works.

GET

Requesting GET at /texts/ provides information on literary works stored in Tesserae’s database.

Request

The following fields may be used in a URL query to filter the response:

Field Name Field Value
author Database information only for texts with the specified author is returned.
after Database information only for texts written/published after the specified year is returned; use negative integers for BCE dates.
before Database information only for texts written/published before the specified year is returned; use negative integers for BCE dates.
cts_urn Database information only for texts with the specified CTS URN is returned.
is_prose If set to “true”, database information only for texts considered prose works is returned; if set to “false”, database information only for texts not considered prose works is returned.
language Database information only for texts with the specified language is returned.
title Database information only for texts with the specified title is returned.

Note that not all texts in the database have a CTS URN, so query by cts_urn may not retrieve desired results.

Also note that query arguments are case-sensitive, so asking for the texts by an author named vergil is different from an author named Vergil.

Response

On success, the response includes a JSON data payload consisting of a JSON object with the key "texts", associated with an array of JSON objects. The JSON objects in the array, in turn, contain the following keys:

Key Value
"author" A string identifying the text’s author.
"object_id" A string which uniquely identifies the text in the Tesserae database.
"is_prose" A boolean value denoting whether the text is considered a prose work.
"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.

Examples

Search by One Field

Request:

curl -i -X GET "https://tesserae.caset.buffalo.edu/api/texts/?author=vergil"

Response:

HTTP/1.1 200 OK
...

{
  "texts": [
    {
      "author": "vergil",
      ...
    },
    ...
  ]
}

Search by Multiple Fields

Request:

curl -i -X GET "https://tesserae.caset.buffalo.edu/api/texts/?after=100&language=latin"

Response:

HTTP/1.1 200 OK
...

{
  "texts": [
    {
      ...
      "language": "latin",
      ...
      "year": 101
    },
    ...
  ]
}

Search with No Results

Request:

curl -i -X GET "https://tesserae.caset.buffalo.edu/api/texts/?language=klingon"

Response:

HTTP/1.1 200 OK
...

{
  "texts": []
}

POST

NB: The POST method for /texts/ is available only on the administrative server

Requesting POST at /texts/ with an appropriate JSON data payload will add the text described by the JSON data to Tesserae’s database.

Request

Appropriate JSON data for a POST at /texts/ must be a JSON object containing the following keys:

Key Value
"metadata" A JSON object specifying the metadata of the work.
"file_contents" A string containing the contents of a .tess file.

The JSON object associated with the "metadata" field of the request object must have the following keys:

Key Value
"author" A string identifying the text’s author.
"is_prose" A boolean value denoting whether the text is a prose work.
"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.

This metadata JSON object is forbidden from containing the following keys: "_id", "id", "object_id".

Response

On success, the response data payload is a JSON object replicating the entry created in Tesserae’s database according to the POST request (in other words, the JSON object associated with the "metadata" key in the request object). Additionally, the Content-Location header will specify the URL associated with this newly created database entry.

The work will be ingested in the background. The ingestion status information is displayed in the database entry associated with the URL specified by the Content-Location header.

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

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

Examples

Upload an Entry for a Text Not in the Database

Request:

curl -i -X POST  -H "Content-Type: application/json; charset=utf-8" \
"https://tesserae.caset.buffalo.edu/api/texts/" \
--data-binary @- << EOF
{
  "metadata": {
    "author": "lucan",
    "is_prose": false,
    "language": "latin",
    "title": "bellum civile",
    "year": 65
  },
  "file_contents": ...
}
EOF

Response:

HTTP/1.1 201 Created
...
Content-Location: /texts/5c6c69f042facf59122418f6/
...

{
  "author": "lucan",
  "object_id": "5c6c69f042facf59122418f6",
  "is_prose": false,
  "path": ...,
  "language": "latin",
  "title": "bellum civile",
  "year": 65
}

Upload an Entry for Text Not in the Database with Insufficient Information

Request:

curl -i -X POST -H "Content-Type: application/json; charset=utf-8" \
"https://tesserae.caset.buffalo.edu/api/texts/" \
--data-binary @- << EOF
{
  "author": "lucan",
  "title": "bellum civile",
  "year": 65
}
EOF

Response:

HTTP/1.1 400 Bad Request
...

{
  "data": {
    "author": "lucan",
    "title": "bellum civile",
    "year": 65
  },
  "message": "The request data payload is missing the following required key(s): language."
}

Upload an Entry for Text Not in the Database with a Prohibited Key

Request:

curl -i -X POST -H "Content-Type: application/json; charset=utf-8" \
"https://tesserae.caset.buffalo.edu/api/texts/" \
--data-binary @- << EOF
{
  "author": "lucan",
  "object_id": "DEADBEEFDEADBEEFDEADBEEF",
  "language": "latin",
  "title": "bellum civile",
  "year": 65
}
EOF

Response:

HTTP/1.1 400 Bad Request
...

{
  "data": {
    "author": "lucan",
    "object_id": "DEADBEEFDEADBEEFDEADBEEF"
    "language": "latin",
    "title": "bellum civile",
    "year": 65
  },
  "message": "The request data payload contains the following prohibited key(s): object_id."
}