The Australian Government coat of Arms

Communities of practice

Communities of practice

HTTP Status Response code 200 OK or 404 Not found for a requested resource not available in backend system

Hello All,

I have a query
as we know GET:/api/customers when executed and returns empty array we return 200 OK Success with [] (an empty array)

for GET: /api/customers/{customer_id} where customer_id=12345 and assume 12345 is not existing in the database or backend system what possible HTTP Status response code shall be returned 200 OK or 404 Not Found

going through this link https://api.gov.au/standards/national_api_standards/api-response.html#http-response-codes
I can say I must use 404 Not Found for the GET: /api/customers/12345 but I received mixed suggestions of using 200 OK in case customer_id=12345 does no exist in database or backend system and use 404 Not Found ONLY when the requested resource URI is not defined in the REST API definition file the interface.

Appreciate your help on this.

Thanks,
Anutosh

Welcome, Anutosh!

In sort: you should return 404

To double-check, you’re asking about a singular resource, not a list of resources like /customers?
Did you mean to say:

“204 OK in case customer_id=12345 does no exist in database”

because returning a 200 and no body doesn’t make much sense to me.

You’ll notice in the standard that you linked that there’s no GET 204 status code.
This is a bit of a holy war and you’ll find a few spirited discussions about this on the web.

Return 404 if the customer can’t be found.
200 OK should be used when the user gets the resource. Empty is not a resource.
If there’s a technical reason why the customer can’t be found (like a server has gone down, or a network issue) then you should return a 5XX error.
The following is a pretty concise example, but remember that the api.gov.au standard doesn’t allow for 204 GET https://stackoverflow.com/a/48036705/905571

You can read the RFC to get a better understanding: https://www.ietf.org/rfc/rfc2616.txt

1 Like

Thanks @svict4 for your reply

My intention is to use 404 Not Found for a resource GET:/api/customers/12345 when customer_id does not exist in the backend system/database.

204 for a GET does not look appropriate as it will be with POST/PUT/DELETE.

But there is so much of debate/discussion going on with in my team for a long time so I thought of checking with the forum members here.

Even the team members provided Queensland Government API Standards https://www.forgov.qld.gov.au/http-status-messages-rms48-no-resource-exists-requested-url and still recommending to use 200 OK when the provided customer_id is not found/does not exist in backend system/database.

I already provided the team with the RFC https://www.ietf.org/rfc/rfc2616.txt but seems like its of no use when following the standards is not a preferred option.

Unfortunately, I can’t help them with the response provided in this forum as well as they are not accepting anymore examples on using 404 Not Found.

P.S. - A decision is still awaited from the team.

Well I’m glad you reached out!

That’s a real shame :frowning: I don’t have a real feel for your situation, but if you’re up for it, you could go the nuclear option…

For Federal, there’s the Digital Service Standard which is mandated (which provides the best opportunity to bring up uncomfortable points). Does QLD have something similar to stage-gate projects?

QGCIO provides a list of policies that projects should conform to: https://www.qgcio.qld.gov.au/publications/qgea-policies,-standards-and-guidelines you might be able to find ammo.

There’s the quote directly on those HTTP status guidelines: https://www.forgov.qld.gov.au/http-status-message-guidelines-overview-and-background

It is therefore important that the Queensland Government takes a consistent approach to the design and appropriate use of HTTP status messages. This means that not only the content of responses but the HTTP headers sent must be consistent across Queensland Government agencies.

I’m also based in Brisbane, so more than happy to have a chat or go for coffee (after covid19 of course :sweat_smile:)