Improvements

[jrf0110]

So, there's lots of little, non-critical specification-related problems that are getting brought up. Let's use this thread to organize our thoughts on how we can improve the API in regards to the HTTP specification, RESTful best practices, and the things we like from well-tested and popular APIs.

• Use 204 on requests that do not send back data http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

[ProCynic]

• Use 201 when a record has been created.
• PUT POST and PATCH should return the new record, or failing that a 204.
• Use 304 when a PUT is successful but doesn't actually change the resource.
• maybe have some ?links=true option to have resources return links to sub-resources.

[pfrazee]

RE: status codes http://httpstatus.es/

I'm all for the better codes. I want to take a shot at producing links via the description yamls at some point; we'll get to it.

[jrf0110]

404 on GET /session when there is no session

[ProCynic]

422 on malformed requests

[jrf0110]

We should get rid of the whole { error: /* .. */, data: /* ... */ } thing.

[ProCynic]

it's much easier client-side if you only have one at a time.

[pfrazee]

would you think, instead, the entire body is an error object if 4xx/5xx, and a data object if 200/201?

[lalitkapoor]

We might not want to make those changes, especially at this point. Since it will mean that the products will need to change the way that they work with the API, which won't be progressive.

if we go this route - clients have to check the http code type before handing the response data... Instead of just checking if an error object exists. Which is the fastest thing to do. We want to make it super easy to adopt and work with the API.

Sent from my iPhone

On Feb 18, 2013, at 4:03 PM, Paul Frazee notifications@github.com wrote:

would you think, instead, the entire body is an error object if 4xx/5xx, and a data object if 200/201?

— Reply to this email directly or view it on GitHub.

[ProCynic]

most networking libraries, jQuery, RestKit, etc., have built in support for checking the http status code and triggering the error handler for anything in the 4xx-5xx range. which means that writing clients is actually a lot easier if we use http properly and have the status code indicate what type of response it is.

[pfrazee]

routes now respond with 204 codes when no content is sent

[jrf0110]

Yeah, we've actually been complicating things by not using built-in error handling. It's an artifact of APIs past!