search

wet-boew / wet-boew-api-standards

Possible requirements for Government of Canada APIs based on the White House standards
Other
11 stars 11 forks source link

Leverage http status code #7

Open LaurentGoderre opened 10 years ago

LaurentGoderre commented 10 years ago

There are a number of very useful http status code that are not included that we should adopt.

For example:

HTTP 201: would be great as a success response to the a post request because the status should include the URL of the created resource via the Location header which would allow chaining operations without the need to create a resource than search for it.

HTTP 401 and 403: those are required when creating authenticated APIs

chrismajewski commented 10 years ago

@LaurentGoderre Another issue to elaborate on.

In the standard we recommend you use appropriate codes and barring a clear correct code use the higher level generic code, particularly [ 200, 400, 500 ], with a full descriptive response tied back to your documentation if possible.

A more descriptive set of response codes and when they are appropriate would be helpful in the standard or as a supplemental document. Consistency across APIs is the key, a document that helps that cause is always welcome.

Something concise for likely scenarios would be ideal.

samperd commented 10 years ago

I have found that 304's (Not Modified) are a great way to learn if the resource or asset you are trying to access is the most up to date one. This can help confirm if a resource has changed or not.

304's have been very useful on the back end to analyse infrastructure and user behavior issues.

more info: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#10.3.5

Cheers

chrismajewski commented 10 years ago

Agreed. It's now in the guinea pig.

The only thing with 304 is that the requesting end has to play along for it to be useful.

It also requires disabling caching, anything in the headers also requires no-cache. ( You can configure varnish and squid to better understand headers but it's not standard or always available in 3rd party caching as a service )

That section can be better defined. 404 is also mis-understood, it's not just for missing "webpages".

chrismajewski commented 9 years ago

The guinea pig is out of my control at this point but it's known that these codes will be required.

Another issue I can't close today.