Collection key names in Zend-Expressive-Hal

Questions Mezzio
#1

Hi,

I’m currently implementing zend-expressive-hal and am wondering why the collection’s pagination properties start with a leading underscore?

Specifically, I have a payload for collection that looks like this:

{
  "_embedded": {
     // stuff
  },
  "_links": {
     // stuff
  },
  "_page": 1,
  "_page_count": 53,
  "_total_items": 993
}

I think that _page, _page_count and _total_items should not have the leading underscore as they are properties of the collection in the same way that a name property exists on a person.

Thoughts?

#2

I had a couple reasons for why I went with the leading underscore:

  • It’s metadata for the collection.
  • The collection resource can have data other than just the embedded collection items. I didn’t want to have conflicts with those (the likelihood of those having a leading underscore is pretty slim).

I’d be okay with removing the leading underscore, but those were my reasons for having them in the first place.

#3

It’s interesting.

While I agree that it’s metadata for the collection, I would say that it’s primary data for the collection resource.

The conflict issue is something I hadn’t thought of, though I think a collection resource with an page and _page property would be very confusing in and of itself.

I wonder if there’s consensus in the wide API community on this?