Hi Steve,
I found the best way to figure out how you need to structure your payload by
working back from what will be consuming it. I recently built the API for
OrionVM and we decided that because we would later be consuming it from a
javascript frontend built in something like Ember.js, we should make it as easy
to consume as possible with that in mind. As it turned out this is also roughly
the same structure expected by most clients e.g. ActiveResource, RestClient,
and Ember.js Datastore.
Here's a few things we did:
- Only send the object/collection in the body
- Send metadata as X- headers
- Use HTTP status codes everywhere to indicate status
- Use root element without object root (see below)
For example, collection response:
Date: Thu, 31 May 2012 22:32:15 GMT
Content-Type: application/json
Status: 200 OK
Content-Length: 154
X-Pagination-Total-Items: 2
X-Pagination-Pages: 1
{
"posts": [
{
"id": 123,
"url": "http://www.example.com/posts/123";
},
{
"id": 124,
"url": "http://www.example.com/posts/124";
}
]
}
Error response:
HTTP/1.1 422 Unprocessable Entity
{
"message": "Validation Failed",
"errors": [
{
"resource": "Post",
"field": "title",
"message": "cannot be blank"
}
]
}
Notice that the collection response is always an object, with a root element of
'posts' and no object root element on the individual items as the type is
denoted by the root element.
The reason we moved all the pagination metadata to the header was to allow HEAD
requests over HTTP which return only the headers, useful for extremely fast
lookups just for counts etc.
As for as embedding the popular_posts collection, IMO this should just be
another resource endpoint you hit. If done right the API response should be
extremely light fast, and if needed implement a rate limit — see Github V3 API.
— Ivan
On 01/06/2012, at 7:13 AM, Steve H wrote:
> Do you have any preferences on good or bad responses from APIs? Or links to
> discussions on this subject.
>
> I'm in the beginning stages of building v2 of an API with feedback from what
> we've learned doesn't work from v1, and want to pick up any other thoughts of
> what might turn out to be a mistake, or things you wish you had added or
> removed from your own APIs after you've built them.
>
> Considerations:
>
> * A common format for error messages
> * Return multiple groups of results in the same response
> * Return metadata about the result set along with the result (e.g. totals)
>
> I'm currently leaning towards something like:
>
> {
> "status":"ok",
> "latest_posts":{
> "total":42,
> "page":1,
> "per_page":10,
> "results":[
> {
> "type":"post",
> "id":123,
> "url":"http://www.example.com/posts/123";
> ...
> }
> ]
> },
> "popular_posts":{
> ...
> }
> }
>
> {
> "status":"error",
> "message":"..."
> }
>
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "Ruby or Rails Oceania" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/rails-oceania/-/tVcxIVy7Q_kJ.
> To post to this group, send email to [email protected].
> To unsubscribe from this group, send email to
> [email protected].
> For more options, visit this group at
> http://groups.google.com/group/rails-oceania?hl=en.
--
You received this message because you are subscribed to the Google Groups "Ruby
or Rails Oceania" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/rails-oceania?hl=en.
