[#37] Use JSON HAL specification for our API endpoints

[krissy]

Addresses issue: #37

What this does

Refactor the existing API implementation to use a modern standard for building hypermedia/HATEOAS APIs. We've chosen the JSON HAL format as it's one of the most well-known standards to date, is easily ignored by clients who don't care about hypermedia and thus recommended for use in public APIs and doesn't mess around with the response too much.

This PR uses a representer pattern to implement this via the Roar gem (and helper gems). The initial plan was to use Activerecord Serializers but this doesn't currently include JSON HAL adapters (only JSON API), and Roar seemed more flexible to work with.

We now also define a custom mime type :hal.

Example calls: /drawings.hal?page=1 (collections, paginated) or /drawings/10.hal (single resource). See example usage below.

Note

This is attempt 1 at defining what our hypermedia endpoints will look like. There are still many things to consider to create a client-self-navigable API, on top of versioning, caching etc. but working iteratively for now. TODO in a next PR:

• Expose more fields, including image URLs. This follows what we currently export in CSV for now, minus organisation data.
• Add previous/next links to collection representation (and possibly single rep)
• Move the API into its own namespace and add versioning, so example calls would be /api/v1/drawings (and no need to post-fix .hal mimetype)

Tasks

• [x] Implement the ability to request a JSON HAL representation of a single drawing resource exposing select fields, e.g. /drawings/1.hal
• [x] Implement the ability to request a JSON HAL representation of a paginated drawing collection, e.g. /drawings/10.hal

Example Requests

Single Resource: /drawings/1.hal

{
    "country": "GR",
    "age": 10,
    "gender": "female",
    "mood_rating": 5,
    "description": "Children and their families in the sea, playing, sunny",
    "story": "Back story of artist",
    "created_at": "2016-08-07T15:44:43.009Z",
    "_links": {
        "self": {
            "href": "/drawings/7.hal"
        }
    }
}

Paginated collection: /drawings.hal?page=1

{
    "total_entries": 5,
    "drawings": [
        {
            "country": "GB",
            "age": 8,
            "gender": "male",
            "mood_rating": 1,
            "description": "Happy days",
            "story": "",
            "created_at": "2016-09-03T17:17:31.040Z",
            "_links": {
                "self": {
                    "href": "/drawings/13.hal"
                }
            }
        },
        {
            "country": "GR",
            "age": 10,
            "gender": "female",
            "mood_rating": 5,
            "description": "Children and their families in the sea, playing, sunny",
            "story": "Back story of artist",
            "created_at": "2016-08-07T15:44:43.009Z",
            "_links": {
                "self": {
                    "href": "/drawings/7.hal"
                }
            }
        },
        {
            "age": 10,
            "gender": "not_specified",
            "mood_rating": 8,
            "description": "Bus and mountains",
            "story": "",
            "created_at": "2016-07-21T22:46:22.617Z",
            "_links": {
                "self": {
                    "href": "/drawings/4.hal"
                }
            }
        },
        {
            "age": 5,
            "gender": "not_specified",
            "mood_rating": 5,
            "description": "test",
            "story": "fsdfds",
            "created_at": "2016-07-16T14:21:06.211Z",
            "_links": {
                "self": {
                    "href": "/drawings/2.hal"
                }
            }
        },
        {
            "age": 5,
            "gender": "not_specified",
            "mood_rating": 5,
            "description": "Test",
            "story": "Leaving home for a while",
            "created_at": "2016-07-16T14:20:39.550Z",
            "_links": {
                "self": {
                    "href": "/drawings/1.hal"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "/drawings.hal?page=1"
        }
    }
}