REST API

README.md

REST API

Demo

You can view a demo here: https://ma-mock-api-tnecfipuho.now.sh/.

Endpoints

Method	Endpoint	Type	Description
GET	/events	List	Lists all events.
GET	/events/:id	Entity	Returns a single event matching on id.
GET	/artists	List	Lists all artists.
GET	/artists/:id	Entity	Returns a single artist matching on id.
GET	/organizations	List	Lists all organizations.
GET	/organizations/:id	Entity	Returns a single organization matching on id.
GET	/locations	List	Lists all locations.
GET	/locations/:id	Entity	Returns a single location matching on id.

List endpoints

These are endpoints that return a list of data with some additional information in the form of filters and helpful headers (for clients that don't allow access to response headers, then use a query parameter to include the meta in the response body).

List endpoints: Query params

Query Param	Value Type	Description
limit	Number	Limits the number of results.
after	ID	Returns a list of results after a given entity ID.
before	ID	Returns a list of results before a given entity ID.
page	Number	Returns a list of results for a given page. Use with limit.
sort	String	Sorts results by the given key. Prepend the value with - to reverse sort.
ids	Comma separated IDs	Returns a list of entities who's ID matches the list provided.
includeMeta	Boolean	Whether the response body should contain pagination info etc.
includeFilters	Boolean	Whether to include some filters in the response body.
filter	Boolean	Whether to include some filters in the response body.

List endpoints: Pagination

Pagination can be achieved by adding query parameters to the request. You just send a limit param with the number of results you want to limit to. You'll get back the next page url in the response header unless you add the includeMeta param to put this information in the body. You can also specify a page param to get results for a specific page number.

curl https://api.mutualart.com/events?limit=5

Should return something like:

HTTP/1.1 200 Successful
Link: <https://api.mutualart.com/events?_limit=10&_after=4f04b42b>; rel="next"
X-total-count: 100
...
{
  "data": [
    {
      "id": 1,
      "name": "Event 1"
    },
    {
      "id": 2,
      "name": "Event 2"
    },
    ...
  ]
}

The number of results in data should be 5, and the response should include a link to the next page of results in the Headers, along with the total count of unpaginated items. If you're on something other than the first page, you might also have a prev link in the Link header.

List endpoints: Filtering (not in the demo)

You can filter lists via query params. You can also request filters that can be applied on the UI layer.

curl https://api.mutualart.com/events?includeFilters=true&filter[museum]=true&filter[location]=paris

Should return something like:

HTTP/1.1 200 Successful
...
{
  "data": [
    {
      "id": 1,
      "name": "Event 1"
    },
    {
      "id": 2,
      "name": "Event 2"
    },
    ...
  ],
  "filters": {
    "type": {
      "name": "venueType",
      "displayName": "Venue Type",
      "type": "list",
      "multi": true,
      "options": [
        {
          "name": "museum",
          "displayName": "Museum",
          "value": true,
          "count": 8
        },
        {
          "name": "gallery",
          "displayName": "Gallery",
          "value": false,
          "count": 15
        }
      ]
    },
    ... # more filters that the UI can render
  }
}