Skip to content

APIs

Jump to bottom
Jacob deGroot-Maggetti edited this page Jul 11, 2023 · 41 revisions

CantusDB APIs

CantusDB's APIs are defined in main_app/views/views.py (code).

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.

The JSON Node Export API may eventually need to be reworked. Since all Chants, Sequences, Sources and Indexers currently (as of October 2022) in the database have been imported from OldCantus, and since all objects in OldCantus are stored as nodes each with their own unique identifier, there are currently no ID collisions between Chants, Sequences, Sources and Indexers. As Chants/etc. begin to be added directly to NewCantus, however, ID collisions may begin to occur. It may eventually be necessary to create a JSON Chant Export API, a JSON Sequence Export API, and so on, so that CantusDB does not return information on an Indexer when another site's developer tries to fetch data on a Sequence with the same ID.

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",
                "srclink": "link to the chant's source's detail page",
                "chantlink": "link to the chant's detail page",
                "folio": "the chant's folio",
                "incipit": "the chant's incipit",
                "feast": "the chant's feast's name",
                "genre": "the chant's genre's name (1 or 2 letters)",
                "office": "the chant's office's name (1 or 2 letters)",
                "position": "the chant's position",
                "mode": "the chant's mode",
                "image": "the chant's image link",
                "melody": "the chant's volpiano",
                "fulltext": "the chant's full text (MS Spelling)",
                "db": "CD"
            },
        },
        {
            "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.

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.

Clone this wiki locally