DEV Community

loading...
Cover image for Blank spaces : how to deal with nothing in API design

Blank spaces : how to deal with nothing in API design

craignicol
Originally published at craignicol.wordpress.com on ・2 min read

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)

Discussion (0)