Which http status code to use for no search results found?

Published on July 04, 2020

Tagged: #engineering

Follow me on twitter for more posts like this

I was implementing a search REST API and was thinking about the no results status. There are a couple of options that are somewhat valid. There is no perfectly “right” answer and the discussion exposes care for API design, knowledge of http and care for developers who will be consuming the api.

The scenario

Say we are searching some rest api for results GET /api/collection?filter=value&filter=value. What should the API return if there are no results?

The go-to response for a non-error is of course 200 OK but I wanted to think it through instead of defaulting to OK. The analysis depends on HTTP code RFC interpretation and conventions around what is a REST response. It’s subjective.

I still ended up preferring 200.

404 Not Found

Not Found sounds like an option that could work well but the 400 series of response codes are used to indicate that the user request was in error.

This is valid in the case where a single entity requested by the user doesn’t exist. The user asked for a resource that doesn’t exist. They should change their request.

But no search results is not a user error (depending on your api of course). No results is an expected response from a collection api like a search filter.

In this endpoint the resource is the collection itself. The collection should exist. Using a 404 could also lead a developer to think that your endpoint/collection doesn’t actually exist when in fact it’s just that there is no data. This could waste a lot of time.

For an issue where the developer tries to search a collection that doesn’t exist. I would return a 404.

204 No Content

No content also sounds like something that might be appropriate. The search was successful but there are no results. This is semantically correct. However the RFC states that

The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields.

So I don’t like this for the fact that a client has to handle no response body. It’s not the worst choice but it feels wrong.

200 OK

This is a great option. It’s straightforward. The request itself was successful.

I feel that having a consistent array in the body is easier to work with and since we design APIs to be consumed as easily as possible.

A 200 OK is the way to go and I was just over thinking this!

Darragh ORiordan

Hi! I'm Darragh ORiordan.

I live and work in Sydney, Australia enjoying the mountains and the ocean.

I build and support happy teams that create high quality software for the web.

Contact me on Twitter!


Read more articles like this one...

List of article summaries

#developer-experience

How engineers can help deliver software effectively

Delivery managers and team leads have the responsibility to deliver a software system via an engineering team.

Your customer wants every feature to work perfectly and they want it delivered yesterday. Your team wants to learn and grow.

It’s a tough role managing all the stakeholders and creators in a project.

Engineers can help drive great delivery by empathising with and supporting the delivery manager or leads in a project team.

#engineering

Engineering systems for consistency and impact

Your most impactful engineering is done before you write any code.

It’s important to have some systems around how you approach problems to make sure you’re consistent every time.

These are some of the techniques I use to make sure I’m covering as many angles as possible when doing my pre-coding engineering.

#engineering

How software engineers can avoid commoditisation

Engineers spend most of their learning time on technical implementation content. Things like new frameworks, languages or cloud platforms.

But turning solutions into code is a tiny part of what you do and it’s getting less valuable year by year.

As we’ve seen with “no-code” and tools like GitHub Copilot, the implementation part of our role is increasingly becoming commoditised.

You could generalise that the value an engineer brings to a team is their ability to analyse problems and synthesise context. The part of your role as an engineer that will never be replaced by “no-code” or AI is this high level cognition.

The true human aspect of being an engineer is working in a team and considering other people’s ideas, emotions and thoughts while solving these problems.

So shouldn’t you train these meta-cognition skills as much as you train the specific technologies?

Every engineer should spend time learning and applying general tools for thinking. These tools are applicable to almost all problems so the compounded payback on your invested time is huge.

Clearer thinking will amplify all the other skills you have and any frameworks or tools you learn will give you results for the rest of your career.

Like any skill, improving the way you think takes deliberate study and practice.

These are some of the tools and systems for thinking that I refer back to all the time.

#engineering

20 questions for a valuable code review

I recently had an interesting discussion around the value of doing code reviews and the value of mandatory code reviews.

I think code reviews are extremely valuable and should be done by most organisations and teams.

A valuable code review will

  • pass institutional knowledge around the org
  • help all engineers grow their skills
  • maintain quality in the face of all the other time pressures your team faces

But how do you keep a code review valuable?