In the absence of a blog post, a few comments:
"status":"ok"
No need for that. That's what HTTP status codes are for.
"page":1, "per_page"
`per_page` should be up to the client. Your API should support
pagination though for retrieving collections, and in which case, it
should accept a range value, or two values, one for range beginning
and range end. The gist here being that some clients might find it
suitable to fetch more, others less, and your API should simply let
those clients decide that. Probably up to a certain number of posts,
of course.
`total` should also be extrapolated from the array length once parsed.
The exception here being if you'd like to supply a separate "metadata"
request for collections which simply returns that kind of info but
omitting the collection itself. That can be handy for some UI cases
(e.g.: showing upfront how many items a collection has before actually
fetching).
That's all from me for now :)
On Thu, May 31, 2012 at 6:13 PM, Steve H <st...@seven.net.nz> 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 rails-oceania@googlegroups.com.
> To unsubscribe from this group, send email to
> rails-oceania+unsubscr...@googlegroups.com.
> 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 rails-oceania@googlegroups.com.
To unsubscribe from this group, send email to
rails-oceania+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/rails-oceania?hl=en.
