Stay In your Lane, App Dev!

There are few experiences in software development that irk me more than design decisions that make support or life for other application developers difficult. Decisions that seem "sensible" or make life a little easier for the application developer who is creating the solution with no regard for the user or other developers are common and can have lasting side effects and sleepless nights for others!

One of the most irritating design decisions is when an application developer uses a concept not indended for their use case in their solution design. One example of this is HTTP response codes. When an application developer creates a web based API, the API response should be consumed by the calling application and interpreted there. Using HTTP response codes causes so many support headaches and is a misuse of the intended purpose.

Consider this example:

Calling system sends: GET https://site.com/GetWidget?WidgetID=1234

System responds: HTTP: 200 OK Content: Widget {ID : 1234, Description: Valid Widget}

But if we send an invalid widget:

Calling system sends: GET https://site.com/GetWidget?WidgetID=1234XXX

System responds: HTTP: 404

In my opinion, this is a fine example of using something against it's intended purpose. It's misleading and you are assuming knowledge from the poor soul who has been called out at 3AM to diagnose an interface issue who simply thinks the application being called is not at the URL specified and it's totally inconsistent unless the ONLY exceptions your API is ever going to respond is unauthorised 403 or not found 404 - if you believe this then you have a better crystal ball than me. The inconsistency will come when you need to craft an application specific error that does not fit the HTTP spec. You will no doubt respond HTTP 200 with an error object response in those scenarios.

HTTP 404 is for the web server's use to respond that the resource is not found. It is NOT for your application to respond that the requested data was not found in your application database. Similarly, unless your API handles authentication in HTTP (eg: HTTP basic authentication as per the HTTP specifications - NOT via your custom header) then please stop responding with a HTTP 403 when authentication fails. The latter request is less of a problem than the 404, admittedly, but let's keep application level responses in our applications and leave the HTTP handling to the web server.