DEV Community

Cover image for Blank spaces : how to deal with nothing in API design
Craig Nicol (he/him)
Craig Nicol (he/him)

Posted on • Originally published at craignicol.wordpress.com on

1 1

Blank spaces : how to deal with nothing in API design

Consider the following HTTP endpoint:

GET /{user}/appointments

How do we deal with nothing?

Nothingman

🚫 If the user doesn’t currently exist, return 404 – this informs the caller that nothing can be done with this resource until it is created or recreated.

🙈 If the user exists, but we want to protect against username enumeration, return 404 – this removes a route for malicious agents to identify actual users, perhaps prior to a password brute force. They may decide this endpoint is less likely to have the full protections afforded to the login endpoint. This endpoint should also avoid indirect enumeration, for example, returning immediately for “user doesn’t exist” and delayed for “user exists but we’re pretending because security”

🔒 If the user exists but the caller doesn’t have permission to see their appointments, return 403 – the caller will have to log in or ask someone who has access.

Empty time

Given the selected user exists

🔐 If this user does not support appointments, return 404 – these resources can’t be found.

🗓 If this user does support appointments, but there are none, return an empty list.

_ note : some APIs will return 204 No Content in this scenario. 204 should only be used for POST or PUT requests to indicate server action was a success, and there’s no data to send back_

Empty space

Given the selected user exists

And they have at least 1 valid appointment (see the business rules for what “valid” means)

📺 If the appointment has no location (because online conference links are saved elsewhere in the appointment body) then no location property should be returned

❔ If the appointment has no location (because it is unknown) then the location property should be returned with no data (the empty string)

Image of Timescale

🚀 pgai Vectorizer: SQLAlchemy and LiteLLM Make Vector Search Simple

We built pgai Vectorizer to simplify embedding management for AI applications—without needing a separate database or complex infrastructure. Since launch, developers have created over 3,000 vectorizers on Timescale Cloud, with many more self-hosted.

Read more →

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more