Dealing with boolean endpoints in a RESTful API

Question

Although there are multiple questions in SO about naming conventions in a RESTful API I can't find any reference on how to deal with boolean endpoints (endpoints that return a boolean value).

Consider an API with the resources /products and /orders.
An order may reference multiple products, so it's not possible to delete a product without messing with related orders.
Calling DELETE /products/:id in a product that is referenced by an order would return a 409 Conflict.

So far, everything is very straight forward, but what if the client wants to confirm if this one product can or cannot be deleted?

A boolean endpoint would return true or false (or a JSON structure containing this value somehow).
GET /products/:id/can-be-deleted

The problem here is that can-be-deleted isn't a (sub)resource, it's an action to check something...
I feel that if RESTful APIs should use nouns and shouldn't have verbs in endpoints it also shouldn't have adjectives (/deletable, /completed) or predicates (/can-be-deleted, /is-ready).

If that is the case, what is the convention on this?
Should this information have it's own endpoint?
If so, how this endpoint should be named?
If not, should this information be part of another endpoint (something like GET /products/:id returning this information)?

VoiceOfUnreason VoiceOfUnreason · Accepted Answer · 2021-04-29T02:11:14

Calling DELETE /products/:id in a product that is referenced by an order would return a 409 Conflict.

So far, everything is very straight forward, but what if the client wants to confirm if this one product can or cannot be deleted?

If you are trying to verify that a resource can be deleted:

OPTIONS /products/1

200 OK
Allow: GET, DELETE
Content-Length: 0

Note that the semantics of DELETE belong to the transfer of documents over a network.

Relatively few resources allow the DELETE method -- its primary use is for remote authoring environments, where the user has some direction regarding its effect. -- RFC-7231

On the web, how do you know if it is OK to submit a form? The answer is simple: the form is provided to you. If you don't get a form (or a link), then you aren't allowed to use it. That's the uniform interface constraint: "hypermedia as the engine of application state."

We add or remove elements from representations to indicate paths you can take through the application. As a client, you check to ensure that your representation is still fresh; if so, then you have the option of sending the request.

The problem here is that can-be-deleted isn't a (sub)resource, it's an action to check something...

Not at all: it's a report about something.

A classic example of an "action to check something" would be a service "health check", the sort of thing that we use to detect that a host needs to be removed from a load balancer.

Any information that can be named can be a resource -- Fielding, 2000

Machines don't care what identifiers we use for our resources; so we can use that freedom to make things easier for people, if we choose to. Usually, a clear understanding of the resource model makes it easy to identify candidate identifiers; so I recommend thinking more about the model when you are having trouble discovering "good enough" identifiers.

Dealing with boolean endpoints in a RESTful API

2 Answers