Skip to content

APIs

Jump to bottom
Jacob deGroot-Maggetti edited this page Feb 27, 2024 · 41 revisions

This page provides documentation on all of the APIs present on CantusDB. It also lists APIs present on OldCantus, and includes some useful APIs from Cantus Index relevant to CantusDB.

CantusDB APIs

Most of CantusDB's APIs are defined in main_app/views/views.py (code), with the exception of /concordances, where Nginx serves a cached file directly.

concordances

The Concordances Export API is used by Cantus Index to compile lists of concordances for various Cantus IDs in all the databases in the Cantus Network. It lists all the chants in the database, with all the necessary values for displaying an item in a list of concordances (refer, for example, to the "Concordances" section at the bottom of a Chant Detail page, or to any CantusIndex ID page).

Nginx serves a cached .json file directly when an agent requests concordances. It is accessible at https://cantusdatabase.org/concordances. This cached file is updated once per day by a cron job that runs the update_cached_concordances command (code).

The API returns an array of JSON objects. Each object represents a single chant from the database, and has the following format:

{
  "siglum": the shelfmark of the chant's source (str),
  "srclink": a link to the chant's source page (str),
  "chantlink": a link to the chant's page (str),
  "folio": the chant's folio (str),
  "sequence": the chant's sequence (i.e. where it appears on its folio - int),
  "incipit": the chant's incipit (str),
  "feast": the name of the chant's feast (str),
  "genre": one or several letters representing the chant's genre (str),
  "office": one or several letters representing the chant's office (str),
  "position": the chant's position within its office (str),
  "cantus_id": the chant's Cantus ID (str),
  "image": a link to view a scan of the page the chant was found on (str),
  "mode": the chant's mode (str),
  "full_text": the chant's full text, in standardized spelling (str),
  "melody": the melody of the chant, represented in Volpiano notation (str),
  "db": "CD" (representing "Cantus Database"; other databases have different abbreviations - str)
}

csv_export

The CSV Export API is used to share information for all chants/sequences in a source in CSV format. It can be accessed via /csv/<source_id> (for example, http://206.12.93.196/csv/123610). It corresponds to OldCantus's csv API.

Each row in the returned CSV file represents a single chant or sequence. It has the following columns:

json_melody_export

The JSON Melody Export API exports information on all chants/sequences in the database with a given Cantus ID in JSON format. It can be accessed via /json-melody/<cantus_id> (for example, http://206.12.93.196/json-melody/002085). It corresponds to OldCantus's json-melody API. It corresponds to OldCantus's json-melody API.

The returned file is an array of JSON objects. Each object represents a single chant. Each object has the following keys:

  • "mid": The value of the chant's melody_id field. A string.
  • "nid": The chant's ID. An integer.
  • "cid": The value of the chant's cantus_id field. A string.
  • "siglum": The value of the chant's siglum field. A string.
  • "srcnid": The ID of the chant's Source. An integer.
  • "folio": The value of the chant's folio field. A string.
  • "incipit": The value of the chant's incipit field. A string.
  • "fulltext": The value of the chant's manuscript_full_text field. A string.
  • "volpiano": The value of the chant's volpiano field. A string.
  • "mode": The value of the chant's mode field. A string.
  • "feast": The ID of the chant's Feast. An integer.
  • "office": The ID of the chant's Office. An integer.
  • "genre": The ID of the chant's Genre. An integer.
  • "position": The value of the chant's position field. A string.

json_node_export

The JSON Node Export API exports all information on a Chant, Sequence, Source or Indexer in JSON format. It can be accessed via /json-node/<id> (for example, http://206.12.93.196/json-node/123610). It corresponds to OldCantus's json-node API.

JSON Node Export returns a single JSON object containing the values of all the fields of the specified Chant, Sequence, Source or Indexer. The JSON object's keys are the names of the fields of the Chant/etc. in question. For more information on these keys and values, refer to the "Fields" sections of the wiki pages on Chants, Sequences, Sources and Indexers. Note that since our internal variable names differ from those used in OldCantus, the keys in this JSON object are different from the keys used in the OldCantus API.

The JSON Node export API does not return responses for objects with IDs greater than 1000000 (one million). It works for all objects imported from OldCantus, but all objects newly created in NewCantus are not guaranteed to have different IDs from objects from other models (e.g. there may be a source with an ID of 1000001 and also a chant with an ID of 1000001), so they cannot be queried using this API.

json_sources_export

The JSON Sources Export API exports information on each published Source in the database in JSON format. It can be accessed via /json-sources (for example, http://206.12.93.196/json-sources/).

The returned file consists of a single JSON object. Each key in the object is the id of one of the database's sources. Each value is a JSON object with a single key-value pair. This single key is always "csv", and the value is a link to the source's CSV Export View. This structure replicates the structure of OldCantus's json-sources API.

json_nextchants

The JSON Next Chants API exports information on which chants tend to follow chants with a given Cantus ID. It can be accessed via /json-nextchants/<cantus_id> (for example, http://206.12.93.196/json-nextchants/007840b). It corresponds to OldCantus's json-nextchants API.

The returned file consists of a single JSON object. Each key in the object is a Cantus ID, and each value is a tally of how many times a chant with that Cantus ID followed a chant with the specified Cantus ID in the database.

json_cid

The JSON CID API exports information on all the chants in the database matching a given Cantus ID. We believe it is used by Cantus Index to generate its table of concordances from all databases in the Cantus Network. It can be accessed via /json-cid/<cantus_id> (for example, http://206.12.88.113/json-cid/007438). It corresponds to OldCantus's json-cid API.

It returns data in the following format:

{
    "chants": [
        {
            "chant": {
                "siglum": the chant's source's siglum (str),
                "srclink": link to the chant's source's detail page (str),
                "chantlink": link to the chant's detail page (str),
                "folio": the chant's folio (str),
                "sequence": the chant's sequence (int)
                "incipit": the chant's incipit (str),
                "feast": the chant's feast's name (str),
                "genre": the chant's genre's name (1 or 2 letters - str),
                "office": the chant's office's name (1 or 2 letters - str),
                "position": the chant's position (str),
                "mode": the chant's mode (str),
                "image": the chant's image link (str),
                "melody": the chant's volpiano (str),
                "fulltext": the chant's full text (MS Spelling) (str),
                "db": "CD" (str)
            },
        },
        {
            "chant": {
                etc.
            }
        }
    ]
}

In case a chant is missing a folio/feast/etc., an empty string substitutes for the null that would otherwise be displayed.

There is one notable difference between OldCantus's implementation of this API and NewCantus's: OldCantus includes a "chantlinkOLD" key in addition to a "chantlink" key. The chantlinkOLD item had a URL with http://, whereas chantlink had a URL with https://. NewCantus doesn't include a chantlinkOLD key.

articles-list and flatpages-list

NewCantus has two APIs that list pages stored in the database. They are used for a link-checking script, which ensures that none of these pages contain dead links. The first API returns a list of URLs, separated by spaces, for all the articles on the site; it is accessible at /articles-list/. The second returns a list of space-separated URLs for all the flat pages on the site, and it is accessible at /flatpages-list.

JSON export APIs for various models

notation/<id>/json

Returns a JSON object with data about a specified Notation, in the following format:

{
  "id" (int): the Notation's ID,
  "name" (str): the Notation's name,
  "date_created" (ISO date/time): when the Notation was created,
  "date_updated" (ISO date/time): when the Notation was last updated,
  "created_by" (int): the ID of the user that created the Notation,
  "last_updated_by" (int): the ID of the user that most recently updated the Notation
}

(as of 2024 Jan 12, this API is not yet live.)

provenance/<id>/json

Returns a JSON object with data about a specified Provenance, in the following format:

{
  "id" (int): the Provenance's ID,
  "name" (str): the Provenance's name,
  "date_created" (ISO date/time): when the Provenance was created,
  "date_updated" (ISO date/time): when the Provenance was last updated,
  "created_by" (int): the ID of the user that created the Provenance,
  "last_updated_by" (int): the ID of the user that most recently updated the Provenance
}

(as of 2024 Jan 12, this API is not yet live.)

OldCantus APIs

csv

Corresponds to CantusDB's csv_export API. It can be accessed via /sites/default/files/csv/<source_id> (for example, https://cantus.uwaterloo.ca/sites/default/files/csv/123610).

In situations where a source has no chants and only sequences, OldCantus outputs a csv file with no rows and only a header.

json-melody

Corresponds to CantusDB's json_melody_export API. It can be accessed via /json-melody/<cantus_id> (for example, https://cantus.uwaterloo.ca/json-melody/002085).

json-node

Corresponds to CantusDB's json_node_export API. It can be accessed via /json-node/<pk> (for example, https://cantus.uwaterloo.ca/json-node/123610).

OldCantus's json-node API is used extensively in the scripts used to migrate data from OldCantus to Cantus DB.

json-sources

Corresponds to CantusDB's json_sources API. It can be accessed via /json-sources/ (for example, https://cantus.uwaterloo.ca/json-sources/).

json_nextchants

Corresponds to CantusDB's json_nextchants API. It can be accessed via /json-nextchants/<cantus_id> (for example, http://cantus.uwaterloo.ca/json-nextchants/007840b).

json-cid

It can be accessed /json-cid/<cantus_id> (for example, https://cantus.uwaterloo.ca/json-cid/006583a). The format seems similar to Cantus Index's json-con concordances API, so it is probably used by CI for compiling its list of concordances.

Cantus Index APIs

Clone this wiki locally