What can we use from HTTP?

Convener

Mitch Oliver (@mitchvoliver)

Attendees

Please add your name and handle if you attended.

Notes

• PLEASE use error codes
• Perhaps a better question is, what should NOT be used? (no answer was proposed)
• Use cache control headers
• Refer to RFC 2616
• Custom "X-" headers
  • not all clients get all headers
  • indicate with special parameters or a PRAGMA
• Reusing error codes may violate the spec
• It was noted that the 30x range is chaotic
• Redefining errors will result in unexpected behavior
• Reusing errors in a sensible manner to add value is recommended
  • keep in harmony with original meaning
  • take time to understand the actual error that occurs
• For authentication, require that a separate resource be created
  • incude above resource in AUTH header after resource is created
• use of OPTIONS verb
  • expose list of available resources
  • hint about how to use resources
• WARNING headers
  • indicate obsolescence
  • indicate deprecation
• Could also use 302 to indicate deprecation
  • HOWEVER: must use versioning in URL and requires request is serviced in the same manner
• Advantage of using HTTP is that tools are well spec'ed; proxies and frameworks understand HTTP already
• Advantage of simplified HTTP with custom error handling is that the learning curve is easier
• Question was posed: Are there any references for using HTTP effectively?
  • Perhaps a heat-map of what is actually used
  • Something that lists beginner, intermediate, and advanced features
• "Overloaded POST" can be used to support actions that do not map cleanly to a resource
  • examples: search and submission
  • "Purchase order" resource has an "action" subresource
    • /purchase_order/action
• It seems that if your API is REST, you should use HTTP; if it isn't rest, take what you like and roll your own
• Are there any mainstream clients that misbehave wrt HTTP spec?
  • Proxy servers are troublesome
• ETags are easy for static content, however they are difficult for dynamic content
  • clients can be flaky with ETags

Common Headers and Expected Results:

• Location header points to newly created resources
• prevent cookie caching with NO CACHE SET-COOKIE
• Use 202 for asynchronous responses
  • provide an indication of expected completion time, perhaps with RETRY AFTER

CONCLUSION!! Read the HTTP Spec.