Contents

Hypermedia

Hypermedia is how you get around the ShootProof API. Hypermedia indicates to your app how things are related and what you’re able to do.

Simply put, hypermedia are links.

At ShootProof, we don’t argue about what is and isn’t RESTful. We use links because they work best for us, and they do a good job telling your app where to go next.

When building an app, pay close attention to the link relations we provide on responses. Each relation means something and tells your app how the data is related. Sometimes the links change and that’s okay. As long as your app knows what the relations mean, it can follow them and adapt.

All API responses we return include link relations that map to either standard link relation types or a ShootProof link relation with meaning specific to the ShootProof API. Link relations are conveyed using a JSON links object, the properties of which are link relations.

The links object consists of one or more properties named according to a link relation. Each relation property may contain a single relation object or an array of multiple relation objects.

Each link will always have an href property. It may also have a few other properties that your app can use.

href
This is the link URL. A link will always have an href. Your app may follow this URL, or it can use it to modify data in some way.
templated
If this is present and true, the href is a templated URI and may be used according to the rules defined in RFC 6570.
type
If this is present, it is a hint for the content type of the link location. If it’s application/pdf, for example, your app will know that it can use this link to download a related PDF. If it’s text/html, that means it’s a URL you may present to a user, and they may click on it to follow it.
title
A title may be present for informational purposes. You may use it to display as the label within your app.

In the following example, the invoice has two alternate representations: PDF and HTML.

{
  "type": "invoice",
  "links": {
    "alternate": [
      {
        "href": "https://api.shootproof.com/studio/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice/91a816b4-394c-4a7f-85ff-7ae6256fe7c2",
        "type": "application/pdf"
      },
      {
        "href": "https://studio.shootproof.com/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice/91a816b4-394c-4a7f-85ff-7ae6256fe7c2",
        "type": "text/html"
      }
    ],
    "collection": {
      "href": "https://api.shootproof.com/studio/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice"
    },
    "self": {
      "href": "https://api.shootproof.com/studio/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice/91a816b4-394c-4a7f-85ff-7ae6256fe7c2"
    }
  }
}