|
Aren't you worried that there is too much "protocol" information in your returned object? I'm struggling with this now. I've come to think the API should return exactly what was requested. So instead of a very specific structured object... "collectionName": {
"total": 861,
"limit": 10,
"offset": 100,
"pages": 87,
"links": [
{"rel": "first", "href": "/api/things?limit=10"},
{"rel": "prev", "href": "/api/things?limit=10&offset=90"},
{"rel": "self", "href": "/api/things?limit=10&offset=100"},
{"rel": "next", "href": "/api/things?limit=10&offset=110"},
{"rel": "last", "href": "/api/things?limit=10&offset=860"},
],
"items": [
...
]
}
It generically returns what was asked for. The items array... [{},{}]
I have seen the "total records" value return in the header with "206 Partial Content" response, but that still leaves the very important "links" information. Right now I am putting a "link-href" value for each object returned, but I don't know where to put the collections link information.Any thoughts are welcome and greatly appreciated! EDIT: Adding to this comment because pfraze's comment below (https://news.ycombinator.com/item?id=5471523). It seems as though the Link Header item could be the appropriate place for this:
http://www.w3.org/wiki/LinkHeader Where does the meta information about the resource belong? In the object/resource returned OR as meta information in the header (with other HTTP information). Is this a needless hindress for |
There's a purity vs pragmatism argument, and I have tried the purity approach several times without success. This time I'm just going for pragmatism... giving developers an easy to use interface that is predictable and consistent.
I just didn't find it constructive to continue pursuing purity when the developers trying to implement the APIs just wanted to get the job done as simply as possible, with all the info at hand, and for them to return to what they were trying to do (usually solve some problem for a user).