# How to format a REST API Billboard/Homepage response

**URL:** <https://discuss.jsonapi.org/t/how-to-format-a-rest-api-billboard-homepage-response/384>\
**Category:** Uncategorized\
**Created:** [March 10, 2016, 5:42pm UTC](https://discuss.jsonapi.org/t/how-to-format-a-rest-api-billboard-homepage-response/384 "2016-03-10T17:42:07Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![josephmcdermott](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/josephmcdermott/32/236_2.png) [@josephmcdermott](https://discuss.jsonapi.org/u/josephmcdermott)\
**Post date:** [March 10, 2016, 5:42pm UTC](https://discuss.jsonapi.org/t/how-to-format-a-rest-api-billboard-homepage-response/384/1 "2016-03-10T17:42:07Z")

</div>

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/](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:

- [How to handle multiple endpoints/links](http://discuss.jsonapi.org/t/how-to-handle-multiple-endpoints-links/212/3)

---

<div class="post-metadata">

**Author:** ![malras](https://avatars.discourse-cdn.com/v4/letter/m/ed8c4c/32.png) [@malras](https://discuss.jsonapi.org/u/malras)\
**Post date:** [March 11, 2016, 3:42pm UTC](https://discuss.jsonapi.org/t/how-to-format-a-rest-api-billboard-homepage-response/384/2 "2016-03-11T15:42:49Z")

</div>

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"}
            }
        }
    }
}    

```

?

---

<div class="post-metadata">

**Author:** ![skarger](https://avatars.discourse-cdn.com/v4/letter/s/45deac/32.png) [@skarger](https://discuss.jsonapi.org/u/skarger)\
**Post date:** [March 11, 2016, 7:26pm UTC](https://discuss.jsonapi.org/t/how-to-format-a-rest-api-billboard-homepage-response/384/3 "2016-03-11T19:26:13Z")

</div>

@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](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.

---

<div class="post-metadata">

**Author:** ![malras](https://avatars.discourse-cdn.com/v4/letter/m/ed8c4c/32.png) [@malras](https://discuss.jsonapi.org/u/malras)\
**Post date:** [March 12, 2016, 7:04am UTC](https://discuss.jsonapi.org/t/how-to-format-a-rest-api-billboard-homepage-response/384/4 "2016-03-12T07:04:11Z")

</div>

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