How to form Hypermedia for Groups and Lists

Question

I am designing a REST API and in this particular use case, trying to figure out the best way and what this hypermedia should look like.

The scenario is that the caller calls /persons?fields=lastName;filter=beginsWith=b because he wants back a list of people whos last names begin with "b".

Below shows the JSON response that I'm trying to figure out how best to mold/represent including hypermedia to associate with.

You can see a list of persons and you only see the name property because it's a partial representation of each person.

Then I try to add HATEAOS in here but not sure what would be the most useful to add and really what that should reference.

I figured ok, I can provide a href to the group (list) itself that I'm returning here. And if that's the case, where? I don't think it makes sense to put it in a root object like I'm doing. Because the expectation is to return a list of people, not also some root meta object so it doesn't feel good to me on what I have below.

OR

Does anyone think it isn't useful or not really embracing the HATEOS in this particular instance and I should instead provide some other type of href links in here?

JSON - List of person objects (representations) returned

[
    "meta": {
        "rel": "self",
        "href": "http://ourdomain.api/persons?fields=lastName;filter=beginsWith=b"
    },
    {
        "name": {
            "last": "best"
        }
    },
    {
        "name": {
            "last": "bettler"
        }
    },
    {
        "name": {
            "last": "brown"
        }
    }
]

francesco foresti · Accepted Answer · 2015-08-28T07:34:31.573

well, it is really your choice here, but I think that if you exclude a representation from navigability (i.e. not providing links to it) then it isn't HATEOAS anymore (just my opinion here). In my opinion you could do something along the lines of the json you provided in the question, just separate clearly what is the result of the call and what is meta-information :

{
  "meta": {
    "rel": "self",
    "href": "http://ourdomain.api/persons?fields=lastName;filter=beginsWith=b"
  },
  "resource" : [
    {
      "name": {
        "last": "best"
      }
    },
    {
      "name": {
        "last": "bettler"
      }
    },
    {
      "name": {
        "last": "brown"
      }
    }
  ]
}

which is not so uncommon. Another approach would be to provide links to the list in every resource you return, with a relation like parent or source (maybe source makes more sense as it is a filtered query), e.g.

{[
   { "name" : {
        "last" : "best"
        },
     "meta": {
        "rel": "source",
        "href": "http://ourdomain.api/persons?fields=lastName;filter=beginsWith=b"
       }
   },
   { ..and so on.. }
]}

after all, the list is just a container for the results, so it would feel more 'clean' (at least to me) not to have any hypermedia in it.

thanks, while you were writing that I just found a nice post where I kinda like how this guy is doing some of it http://phlyrestfully.readthedocs.org/en/latest/halprimer.html — PositiveGuy, Aug 28 '15 at 08:15
I'll post what I ultimately went with in a few as a follow-up. — PositiveGuy, Aug 28 '15 at 08:15

How to form Hypermedia for Groups and Lists

1 Answers1