How to format a REST API Billboard/Homepage response

1

I am developing a REST API using JSON API as the standard format for request and response data, but struggling to decide on a format for the data returned by the Hompage / Billboard page, ie: when the consumer visits http://api.example.com/.

The goal is to display the next available steps that the consumer can take, which for this example are /people and /products, and below is the best I could come up with in terms of presenting this data:

{
    "links": {
        "self": "http://api.example.com"
    },
    "data": [
        {
            "type": "Link",
            "id": "people",
            "attributes": {
                "id": "people",
                "href": "http://api.example.com/people"
            }
        },
        {
            "type": "Link",
            "id": "products",
            "attributes": {
                "id": "products",
                "href": "http://api.example.com/products"
            }
        }
    ]
}

I am not entirely keen on this as it feels like the data being returned fits better within the top level “links”, however according to the specification we must have at least a “data” or “meta” element, so I went with “data”. This means I am required to include some superfluous information (id, type and attributes), when all I really want to include is a “self” link with the relevant href.

I would love to hear some alternative solutions on how to solve this one!

Update:
I have since found some other topics, and it appears as though this is still officially ‘unanswered’ in the JSON API specification:

2

something like:

{
    "data": {
        "type": "/",
        "id": null,
        "links": { "self": "http://api.example.com" },
        "relationships":{
            "people":{
                links: {"related": "http://api.example.com/people"}
            },
            "products":{
                links:{"related": "http://api.example.com/products"}
            }
        }
    }
}

?

3

@josephmcdermott: I’ve had the same question. The approach I’ve taken is basically what @malras described except that by the spec it looks like the related link should be within links object.
http://jsonapi.org/format/#document-resource-object-relationships

{
  "data": {
    "type": "home",
    "id": "1",
    "links": {
      "self": "http://api.example.com"
    },
    "relationships": {
      "people": {
        "links": {
          "related": "http://api.example.com/people"
        }
      },
      "products": {
        "links": {
          "related": "http://api.example.com/products"
        }
      },
      "account_representative": {
        "meta": {
          "uri_template": "http://api.example.com/account_representatives/{person_id}",
          "description": "Fetch the profile of one of your account representatives, whose ids you know independently."
        }
      }
    }
  }
}

I’ve also considered your original approach, where the next steps people can take from the API entry point are themselves resource objects, for example of type “Link” as you have above, and the home page returns an array of those resource objects as the primary data. Both seem valid per the spec; I’m not sure yet what will ultimately work better in practice.

1 Like
4

thanks @skarger for the comment, indeed I have missed the “links” before “related”.
I updated my example accordingly.