In a previous tip, I explained how we use a simple middleware to force all API requests to explicitly accept JSON.
One of the reasons I cited was that it reduces support requests.
If they don't specify the right header, we not only return the appropriate HTTP 406 Not Acceptable status code, but we also return a friendly message explaining what they did wrong and how to fix it.
But on a recent project, an external consumer of this API was sending Accept: */* in the request header, and still contacted me to complain about it not working, even with my helpful error.
I could chalk this up to "not a great dev", but I used it as an opportunity to take a step back and think about this approach. Does it still make sense to be so strict? I'm open to changing my mind if it makes sense.
First, what would the alternative be?
I could change the wantsJson() to an acceptsJson() check, which would allow Accept: */* to pass.
This would still enforce that they accept JSON, but it would be more permissive.
Another approach could be to add some logic to check for Accept: */* specifically, and return a different message explaining that they should be more specific.
Ultimately though, I think I'll stick with my original approach. I want to encourage my API consumers to be explicit about what they want. This helps avoid ambiguity and prevents all the noise and unhandled exceptions mentioned in the original article.
One change I am making is a more explicit note in the onboarding documentation making it even more clear that they need to set the Accept header specifically to application/json.
Hopefully that will avoid similar support requests in the future.
Here to help,
Joel
P.S. Does your application have an API, public or internal-facing? Would you like some help writing and enforcing an API specification?