Making Requests


Reminder

Remember to always include your API key in the URL, like so:

curl -H 'Guitarparty-Api-Key: {API_KEY}' http://api.guitarparty.com/v2/songbooks/

where {API_KEY} is your API key.


Request methods

Most endpoints in our API suppert at least one HTTP verb; GET. The general rule is that when you are dealing with objects that are directly associated with your user account, such as songbooks or favorite songs, you can use all four verbs (GET, POST, PUT, DELETE). When you are dealing with objects that are moderated by our super users and belong to everyone - so to speak - like songs and authors, you can only use GET.

This effectively means you can search and fetch most of our available data but you can only change data that belongs exclusively to your user account.


Data format

We only accept JSON as input data and all data is output in JSON. We might include other options such as XML, YAML or whatever the cool kids on the block are using at any given moment, but we support JSON because it simply rocks!

The data that we output follows a simple rule. If you are explicitly fetching a single object, you get that object directly:

curl -H 'Guitarparty-Api-Key: {API_KEY}' http://api.guitarparty.com/v2/songs/5/
{
    "body": "...", 
    "chords": [...],
    "tags": [], 
    "title": "Jolene", 
    "uri": "/v2/songs/5/"
}

If you are fetching a list of objects, you get a JSON object with a list named objects:

curl -H 'Guitarparty-Api-Key: {API_KEY}' http://api.guitarparty.com/v2/songbooks/
{
    "objects": [
        {
            "description": "", 
            "is_public": false, 
            "title": "G\u00edtargaurinn", 
            "uri": "/v2/songbooks/1/"
        }
    ], 
    "objects_count": 1
}

The same goes for POST requests. Consider this JSON file called postdata.json:

{
    "title": "The Beatles Collection",
    "description": "A witty description"
}

When this data is POST'ed to the proper API endpoint, the API de-serializes the JSON parameters and treats them appropriately. In this case we want to create a new songbook called The Beatles Collection with a description of A witty description.

curl -X POST -H 'Guitarparty-Api-Key: {API_KEY}' \
    http://api.guitarparty.com/v2/songbooks/ -d @postdata.json
{
    "description": "A witty description", 
    "is_public": false, 
    "title": "The Beatles Collection", 
    "uri": "/v2/songbooks/12345/"
}

The resulting songbook object is returned in JSON format with status code 201 CREATED.