Please note, we are in the process of retiring the public api. The public api, as well as its documentation and playground, will remain available until July 28th, 2025. This change will not affect integration partners using our partner api.


If you're an Artsy partner gallery, reach out to your Artsy Liaison or contact our Support team for assistance.

Public API Documentation > General > Links Between Resources

Links Between Resources

Links in HAL responses are contained directly within a resource. Thet are represented as a JSON object contained within a "_links" hash.

{
    "_links" : {
        "next" : {
          "href": "https://api.artsy.net/api/..."
        }
    }
}

API Discoverability

A HAL API should be navigated from its root. The root itself is a collection of links.

Link Relations

Links have a relation, aka. "rel". This indicates the semantic, the meaning, of a particular link. Link rels are the main way of distinguishing between a resource's links. It's basically just a key within the "_links" hash, associating the link meaning (the 'rel') with the link object that contains data like the actual "href" value:

{
    "_links" : {
        "artworks" : {
          "href": "https://api.artsy.net/api/..."
        }
    }
}

The "rel" above is "artworks" and can be typically found in an artist JSON object. Link rels are URLs which reveal documentation about the given link, making them "discoverable".

Templated Links

Templated links have a "templated" attribute set to "true".

"_links" :
  "artist" : {
    "href" : "https://api.artsy.net/api/artists/{id}",
    "templated" : true
  }
}

Query string parameters are declared as follows.

"_links" :
  "artist" : {
    "href" : "https://api.artsy.net/api/artworks{?public,artist_id}",
    "templated" : true
  }
}