Resource Types

You must discover the URL paths to all resource types with the URLs provided by the server. However, resource types available in a context will always be named consistently. Those names are given at the root URL as described in the Root URL JSON Specification.

Consider the following example, of submitting a request to the root URL:

GET / HTTP/1.1
HTTP/1.1 200 OK

...
{
    "resources": {
        "browse": {
            "genre": "/genres/",
            ...
            },
        "view": {
            "genre": "/view_genre/id?",
            ...
            },
        ...
    }
}

To retrieve a paginated list of all genres, you would submit a GET request to /genres/. To access information about a particular genre, say genre 25, submit a request to /view_genre/25/. On a different deployment, or with a different implementation or version of the Cantus server, the URL path may be entirely different (e.g., /genre-browser). However, if ["browse"]["genres"] appears in the "resources" member of a response, it will always point to the list of genres, and ["view"]["genres"] will always give information related to a specific genre.

While the URLs are unlikely to change frequently (possibly never) in the above example, in the following example it is much more important to pay careful attention to using the URLs provided by the server in the “resources” member.

You submit a query about “Benedicamus patrem et filium” chants:

SEARCH https://abbott.uwaterloo.ca/chants/ HTTP/1.1

{"query": "'benedicamus patrem et filium'"}
HTTP/1.1 200 OK

...
{
    "556270": {
        "source": "Wolfenbüttel, Herzog August Bibliothek - Musikabteilung, 32",
        ...
    },
    "436440": {
        "source": "Salamanca, Catedral - Archivo Musical, 6",
        ...
    },
    "pem-8669": {
        "source": "P-Cug (Coimbra) Biblioteca Geral da Universidade MM 45",
        ...
    },
    "resources": {
        ...
        "556270": {"self": "https://abbott.uwaterloo.ca/chants/556270/"},
        "436440": {"self": "https://abbott.uwaterloo.ca/chants/436330/"},
        "pem-8669": {"self": "http://pemdatabase.eu/musical-item/8669"},
        ...
    }
}

While the Cantus server has cached some metadata about all the chants, you can see from the provided URLs that resource "pem-8669" is actually hosted on the Portuguese Early Music server, and we refer the client to that URL for further information. Note also that the “id” field is not consistent between the two servers: in this case, the uwaterloo.ca Cantus server has prefixed the pemdatabase.eu server’s “id” with "pem-" to avoid a resource “id” conflict.

As a reminder, the Cantus server will only “switch out” a resource provider like this when it is API-compatible, so this “resources” URL represents a promise that the PEM server supports the Cantus API. For more information, refer to Multi-Server Interoperabilty.

About the “id” Field

For “view” URLs, where id? makes part of the server-provided URL, user agents MUST form a full URL by substituting a resource’s unique “id” value in that part of the URL. The full three-character string, id?, must be removed from the URL.

Cantus API “id” values may consist of the characters A through Z, a through z, and the digits 1 though 0, plus hyphens and underscores. The first and last characters of an “id” MUST NOT be a hyphen or underscore (- or _). If a user agent requests a resource with an invalid “id” the server MUST respond with the 422 Unprocessable Entity HTTP status code.

The following points also apply:

  • A resource’s “id” MUST refer to the same resource through the existence of that “id.” However, a resource may change its “id” at any time.
  • Changing attributes, properties, or data in a resource MUST NOT change the “id” field.
  • A resource’s “id” field MAY be prefixed with an identifier indicating which database holds the resources’s authoritative copy.
  • The same “id” MAY or may not refer to “the same” resource when served by a different deployment of a Cantus server application. That is, the Cantus API does not guarantee uniqueness of “id” values across deployments.

Simple Resource Types

Unlike the types listed in the following section (Complex Resource Types) the resources in this category will not have fields that cross-reference another resource. Simple resources also tend to have fewer fields, and are not expected to change often during the lifetime of the database—perhaps never.

GET /(view.simple_resource)/(string: id)/

Most simple resources follow this pattern.

Response JSON Object:
 
  • id (string) – The “id” of this resource.
  • name (string) – Human-readable name for the resource.
  • description (string) – Brief explanation of the resource.
  • drupal_path (string) – Optional URL to this resource on the Cantus Drupal instance.

The following simple resource types use the default fields described above:

  • century
  • notation
  • office
  • portfolio categories
  • provenance
  • RISM siglum (pl. sigla)
  • segment
  • source status

Three simple resource types use additional fields, or different fields, than those described above.

Indexer

GET /(view.indexer)/(string: id)/

An “Indexer” corresponds to a human who has entered or modified data in the Cantus Database. The set of fields is entirely different from other simple resource types.

Response JSON Object:
 
  • id (string) – The “id” of this resource.
  • display_name (string) – The indexer’s name, as displayed.
  • given_name (string) – The indexer’s given name.
  • family_name (string) – The indexer’s family name.
  • institution (string) – The indexer’s associated university or research institution.
  • city (string) – The city where the indexer lives.
  • country (string) – The country where the indexer lives.
  • drupal_path (string) – Optional URL to this resource on the Cantus Drupal instance.

Feast

GET /(view.feast)/(string: id)/

Feast resources add two fields over the standard set for “simple” resources.

Response JSON Object:
 
  • id (string) – The “id” of this resource.
  • name (string) – Human-readable name for the feast.
  • description (string) – Brief explanation of the feast.
  • date (string) – Date on which the feast occurs.
  • feast_code (string) – Standardized feast code for the feast.
  • drupal_path (string) – Optional URL to this resource on the Cantus Drupal instance.

Genre

GET /(view.genre)/(string: id)/

Genre resources add one field over the standard set for “simple” resources.

Response JSON Object:
 
  • id (string) – The “id” of this resource.
  • name (string) – Human-readable name for the genre.
  • description (string) – Brief explanation of the genre.
  • mass_or_office (string) – A case-insensitive string, either "mass" or "office".
  • drupal_path (string) – Optional URL to this resource on the Cantus Drupal instance.

Complex Resource Types

The following resource types (Chant and Source) hold many data fields, some of which cross-reference a simple resource described in the previous section, or another complex resource.

Chant

GET /(view.chant)/(string: id)/

A “Chant” resource is a chant written in a Source. These are available at the URLs indicated by ["view"]["chant"] and ["browse"]["chant"].

Response JSON Object:
 
  • id (string) –
  • incipit (string) –
  • source (string) – the “title” field of the corresponding “Source” resource
  • marginalia (string) –
  • folio (string) – E.g., "05v"
  • sequence (string) –
  • office (string) – the “name” field of the corresponding “Office” resource
  • genre (string) – the “name” field of the corresponding “Genre” resource
  • position (string) –
  • feast (string) – "name" field of the corresponding “Feast” resource (e.g., “Dom. 21 p. Pent.”)
  • feast_desc (string) – "description" of the corresponding “Feast” resource (e.g., “21st Sunday after Pentecost”)
  • mode (string) – (will appear in "resources" after the first version)
  • differentia (string) –
  • finalis (string) – (will appear in "resources" after the first version)
  • full_text (string) – "full_text"
  • full_text_manuscript (string) – full text as written in the manuscript
  • volpiano (string) – neume information to be rendered with the “Volpiano” font
  • notes (string) –
  • cao_concordances (string) –
  • siglum (string) – the “siglum” field of the corresponding “Source” resource
  • proofreader (string) – "display_name" of an “Indexer” resource
  • melody_id (string) – (will appear in "resources" after the first version)
  • drupal_path (string) – Optional URL to this resource on the Cantus Drupal instance.
  • proofread_fulltext (string) – Whether the “fulltext” field was proofread.
  • proofread_fulltext_manuscript (string) – Whether the “fulltext_manuscript” field was proofread.
  • resources>source (string) – URL to the containing “Source” resource
  • resources>source_id (string) – resource ID for previous
  • resources>office (string) – URL to the corresponding “Office”
  • resources>office_id (string) – resource ID for previous
  • resources>genre (string) – URL to the corresponding “Genre”
  • resources>genre_id (string) – resource ID for previous
  • resources>feast (string) – URL to the corresponding “Feast” resource
  • resources>feast_id (string) – resource ID for previous
  • resources>image_link (string) – URL to an image, or a Web page with an image, of this Chant
  • resources>proofreader (string) – URL to an “Indexer” resource
  • resources>proofreader_id (string) – resource ID for previous

Source

GET /(view.source)/(string: id)/

A “Source” resource is for a collection of folia containing Chants (usually a book). These are be avialable at the URLs indicated by ["view"]["source"] and ["browse"]["source"].

Response JSON Object:
 
  • id (string) – The “id” of this resource.
  • title (string) – Full Manuscript Identification (City, Archive, Shelf-mark)
  • rism (string) – RISM number
  • siglum (string) – Siglum
  • provenance (string) – Provenance
  • provenance_detail (string) – More detail about the provenance
  • date (string) – Date
  • century (string) – Century
  • notation_style (string) – Notation used for the source
  • editors (string) – List of "display_name" of indexers who edited this manuscript
  • indexers (string) – List of "display_name" of indexers who entered this manuscript
  • proofreaders (string) – List of "display_name" of indexers who proofread this manuscript
  • segment (string) – Segment (i.e., source database)
  • source_status (string) – Status of this source
  • source_status_desc (string) – Elaboration of "source_status"—probably never used.
  • summary (string) – Summary
  • liturgical_occasions (string) – Liturgical occasions
  • description (string) – Description
  • indexing_notes (string) – Indexing notes
  • indexing_date (string) – Indexing date
  • drupal_path (string) – Optional URL to this resource on the Cantus Drupal instance.
  • resources (object) – Links to other indexer who share the same characteristics.
  • resources>provenance (string) –
  • resources>provenance_id (string) – resource ID for previous
  • resources>century (string) –
  • resources>century_id (string) – resource ID for previous
  • resources>notation_style (string) –
  • resources>notation_style_id (string) – resource ID for previous
  • resources>editors (string) – List of URLs to Indexer resources.
  • resources>editors_id (string) – resource ID for previous
  • resources>indexer (string) – List of URLs to Indexer resources.
  • resources>indexer_id (string) – resource ID for previous
  • resources>proofreaders (string) – List of URLs to Indexer resources.
  • resources>proofreaders_id (string) – resource ID for previous
  • resources>source_status (string) –
  • resources>source_status_id (string) – resource ID for previous
  • resources>image_link (string) – Root URL linking to images for the entire source.