RESTful errors, Simple Boot

Handling Errors

Reading Travis McChesney's RESTful API Design Part III: Error Handling, there are more ways to represent errors in REST APIs than the returned body. A toy API I am writing as a playground for these idea is named Simple Boot, a jest on "Spring Boot". There I have an "X-Correlation-ID" header for tracking calls through services.

• Should "X-Correlation-ID" be required?
• Should it be supplied automatically?
• When required and missing, what should the caller receive?

Answering the third the caller sees:

HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
Warning: 250 localhost:8080 "Missing X-Correlation-ID header"
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 28 May 2015 12:46:40 GMT
Connection: close

{
  "timestamp": 1432817125588,
  "status": 400,
  "error": "Bad Request",
  "message": "Missing X-Correlation-ID header",
  "path": "/hello/Bob"
}

Here rather than choosing among options, I take them all:

1. Return a 400 for a bad request
2. Describe the error in the response body
3. Add a header describing the error

As McChesney points out, there is not general agreement on reporting errors. For example, Facebook returns 200 for errors, requiring parsing of the response body.

Using the "Warning" header for this purpose is uncommon but supported in the specification albeit obliquely. However not everyone agrees. I use warning code 250, one I made up. The 1xx codes are transient errors; the 2xx codes permanent. In another example I use a 1xx code for an upstream service currently unavailable, and return cached data, which is closer to the described uses of "Warning".

Other header options:

• Using a custom code outside 1xx or 2xx with "Warning". This makes sense for in-house services, may cause issues with caching devices but unclear
• Use a custom HTTP header, a common solution, again may have issues with intermediate devices

Some Spring Bonus

Simple Boot has been fun and instructive. One Spring Boot feature I stumbled on is automated binding of configuration properties. For services requiring "X-Correlation-ID" I configure with @ConfigurationProperties(prefix = "headers.correlation-id.server"). To automate clients I use @ConfigurationProperties(prefix = "headers.correlation-id.client").

As an example of solving one issue with headers, I write Feign pass-through support.

Of course there are tests.