In Oxford they ripped my logging examples to shreds. In Cambridge I couldn’t convince anyone of the merits of sharing data - so I reframed it in terms of caching. In Colchester they were convinced that it was fine to return a success indicator in a HTTP response body - this resulted in me writing, Should HTTP Status Codes Reflect Business Outcomes?. And in London someone started arguing after just the second slide, but they, and the rest of the audience, went on to ask rich and engaging questions.
In Norwich, my home city, and off the back of me describing what had gone on in Colchester a few weeks before, a couple of different people asked me some questions I felt needed addressing more fully than a few tweaks to my presentation for the next time. I’m going to explore the answers here, and this, together with the introduction of the new Query verb for RESTful interfaces, will most likely result in a much needed update to my RESTful Behaviour Guide.
What to return when something unauthorised is requested?
Imagine this scenario:
An authenticated or unauthenticated client makes a call to a RESTful interface for a resource they are not authorised to have.
Obviously, they should not be given the resource, but what should the response code be? I think most of us have been here and felt conflicted, but the answer only requires a little thought and remembering that there are bad actors out there.
The client is not authorised to have the resource, so the obvious response code is 403 - FORBIDDEN (or 401 - UNAUTHORIZED if the client is not authenticated). However, if the client subsequently requests a different resource which does not exist and receives a 404 - NOT FOUND, they can infer that the original resource exists. That gives them information they didn't previously have, which could help an attacker enumerate valid resources.
Therefore, for resources whose existence should not be disclosed, the response should be 404 - NOT FOUND, whether the resource does not exist or the client is not authorised to access it. This prevents clients from distinguishing between the two cases and avoids leaking information about protected resources.
What to return if a downstream service fails?
Imagine you call a service, which in turn calls a second service as part of the same synchronous request. The second service may then call a third service, and so on. If one of the services in the chain returns a non-2XX status code, should the overall response status code indicate success or failure?
In Should HTTP Status Codes Reflect Business Outcomes, I argue that an HTTP response code doesn’t just reflect the success or failure of the HTTP request; it also reflects the success or failure of the operation carried out by the service. If either the HTTP request or the operation fails, the overall request should be considered to have failed.
Synchronous HTTP requests fulfilled through a chain of services should be considered a transaction. Therefore, if any service in the chain returns a failure status code, the overall request should also be considered to have failed. Only if every service in the chain completes successfully should the overall request be considered successful.
There will always be exceptions, for example when parts of the task performed by the service chain are permitted to fail. In these circumstances, the 207 - MULTI-STATUS response code () can be used, indicating that the overall operation was successful while signalling that the client should inspect the response body for details of any partial failures.
What is the right verb for signalling the end of a batch?
Imagine multiple distributed clients need to contribute data to the same batch through a RESTful interface. Rather than sending everything in a single request, perhaps because the batch is too large or the data is produced by different systems, the clients send the individual items independently. At some point, the service needs to know that no more items are coming and that the batch is complete.
The obvious question is: how should the service know that the batch is complete, and what HTTP verb should be used to signal it?
The answer is that there isn’t one.
HTTP verbs describe the operation being performed on a resource. They do not describe events in a process, such as “I have finished sending things”. The mistake is thinking about this as a protocol problem rather than a resource modelling problem.
A better approach is to model the batch itself as a resource:
POST /batches
creates the batch, returning something like:
Location: /batches/123
The clients can then add items to the batch:
POST /batches/123/items
When the clients have finished adding items, one of them changes the state of the batch:
PATCH /batches/123
{
"status": "complete"
}
The important thing here is that the client is not sending a special “end of batch” command. It is updating the state of a resource.
Sometimes completion is not just a state change, but an instruction to start some processing. In that case, it may be more appropriate to model that as an action:
POST /batches/123/process
The distinction is subtle but important. “The batch is complete” is a statement about the resource. “Process this batch” is an instruction to perform an operation.
As with many REST design decisions, the key is to avoid thinking about verbs and start thinking about resources and their lifecycle. HTTP already gives us the verbs we need; the challenge is modelling the things those verbs operate on.
Finally
The irony is that I wrote a talk about designing services that stand the test of time, but the talk itself keeps changing. Every audience has found something I hadn’t considered, challenged an assumption, or forced me to explain something more clearly. That’s probably the best thing about speaking at communities like these: it isn’t a one-way transfer of knowledge, it’s a conversation. So thank you to everyone who has listened, argued, questioned, and occasionally torn my examples apart. You’ve made the talk better, and I suspect there are still plenty more blog posts hiding in the questions I haven’t answered yet.
* I haven’t actually given my talk in York at the time of writing.
Comments
Post a Comment