Request and Response Bodies

Request Bodies

In the first version of the Cantus API, the only type of request that has a request body is a search. Refer to How to Search for more information. Request bodies will be more widely used in subsequent versions of the Cantus API, especially for updating and uploading new records.

Response Bodies

Note

The response body examples below are not intended to represent actual data—always check the “resources” URLs provided by the server, rather than generating them on the client side.

Note

Every resource has will have at least two fields: id and type.

Response bodies are JSON formatted, which reduces complexity for client applications written in JavaScript. They always have the same form:

{
    "id_value": {
        "id": "id_value",
        "type": "example_resource",
        "fieldA": "value",
        "fieldB": "value"
    },
    "resources": {
        "id_value": {
            "fieldA": "value URL",
            "fieldA_id": "someID",
            "fieldB": "value URL",
            "fieldB_id": "otherID"
        },
    },
    "sort_order": [
        "id_value"
    ]
}

Only fields with data will be included in a response, regardless of which fields are requested. In addition, hyperlinks to corresponding resources are automatically included whenever possible, in the “resources” member of the response body. Consider the following example:

{
    "361434": {
        "id": "361434",
        "type": "chant",
        "incipit": "Dixit dominus paralytico",
        "cantus_id": "002288",
        "feast": "Dom. 21 p. Pent.",
        "feast_desc": "21st Sunday after Pentecost"
    },
    "resources": {
        "361434": {
            "self": "/chants/361434cantus/",
            "feast": "/feasts/1616/",
            "feast_id": "1616"
        }
    },
    "sort_order": [
        "361434"
    ]
}

The response body tells us that this chant occurs during the feast called “Dom. 21 p. Pent.” which is the “21st Sunday after Pentecost,” and that more information about this feast is available at the /feasts/1616/ URL. In general, some fields may not have corresponding “resources” members, and some “resources” fields may not have corresponding data fields.

Use the HEAD method to fetch the X-Cantus-Fields header to determine which fields are available for a particular resource.

Sort Order

The 'sort_order' member MUST be included in a response body, containing a list of the resource IDs in that response body. This list is the only means to provide a response to the X-Cantus-Sort header, or to provide relevance-based sorting of search results. User agents MAY ignore the 'sort_order' if they wish.

Note in the following section, for example, that the 'sort-order' indicates the two resources should be displayed in the opposite order they appear in the JSON response itself.

Response Bodies to Searches

The only difference between the response body for a specific resource, for a collection of resources at the “browse” URL, and the result of a search, is that search results may include resources of more than one type. Thus the “type” member is important in this case to know how results should be displayed. For example:

{
    "361434": {
        "id": "361434",
        "type": "chant",
        "incipit": "Dixit dominus paralytico",
        "cantus_id": "002288",
        "feast": "Dom. 21 p. Pent.",
        "feast_desc": "21st Sunday after Pentecost"
    },
    "123673": {
        "id": "123673",
        "type": "source",
        "title": "München, Franziskanerkloster St. Anna - Bibliothek, 12o Cmm 1",
        "provenance": "Italy"
    },
    "resources": {
        "361434": {
            "self": "/chants/361434cantus/",
            "feast": "/feasts/1616/",
            "feast_id": "1616"
        },
        "123673": {
            "self": "/books/123673/",
            "provenance": "/provenances/3608/",
            "provenance_id": "3608"
        }
    },
    "sort_order": [
        "123673",
        "361434"
    ]
}

For more information about searching, refer to How to Search.