Skip to content

APIs

Jump to bottom
Jacob deGroot-Maggetti edited this page Oct 11, 2022 · 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 returns a list of Cantus IDs along with a tally of how many times chants with that Cantus ID followed chants with the given Cantus ID in the database. 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.

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).

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).

Clone this wiki locally