What's the convention to name a REST endpoint that returns a boolean?

Question

I have an endpoint that returns whether a resource is valid or not (true or false):

GET resource/{id}/valid

Where the returned value is not a field of the resource and is dynamic, it does not depend on the resource alone but on other factors that can change in time, meaning that if I call it today and returns true, tomorrow may return false on the same resource.

According to REST naming conventions adjectives - such as "valid" - should not be used but I am struggling finding a better alternative. Even if /valid does not follow the REST conventions it does a good job in conveying what the endpoint is expected to return.

What is the recommended way to name such endpoints?

Edit: great arguments in the answers, thanks everyone for their contribution! I want to add that a requirement here is to return only true or false, in order to minimize network utilization and serialization and deserialization processes.

Answer 1

I am not sure if you are using "valid" as a synonym for "exists". If so the extra path (/valid) is redundant you can simply return a 404 (not found) if the resource doesn't exist.

Valid is an attribute

Assuming that that a resource can both exist and be invalid at the same time, it appears that the "valid" status is an attribute of the resource. As such you should simply include it in the response for example if you are using JSON, you would simply include:

...
"valid": true,
...

Use filtered HEAD Request

I am going to assume that you have some (performance based) objection - that you don't need to return the full object and/or calculating the full object is expensive. If so you could use a HEAD request with a filter:

HEAD resource/{id}?valid=false

The concept being that if there are no resources that satisfies the filter you can legitimately return a 404. If you don't like 404 for this case, I can also make a case for several other 4xx status codes.

Use Accept Header/Mime Types

In the same way that you can request the format (JSON/XML) from a REST endpoint. You could consider the "valid" status to be a summary / different type of response.

I didn't see anything appropriate in the standard mime types so you would probably have to make something up like: Application/valid

NOTE: As I have added more suggestions here, each one feels like more of a Kludge than the last one so I would strongly favor my earlier suggestions.

Answer 2

According to REST naming conventions

REST doesn't care what spelling conventions you use for your resource identifiers.

/resource/{id}/valid

is fine.

---

It sounds like you are expecting the representation of /resource/1/valid to describe, in some way, information about the resource /resource/1. That's a perfectly normal sort of thing to do - it might be a digest, or a summary, or just some domain specific metadata.

Which is to say, you might be happier if you can find a spelling that better describes the role that the representation plays.

---

You might also want to consider whether a separate resource is the best way to communicate this information to the client, vs including it in the metadata of your responses to GET /resource/1.

You could, for example, use a link relation, in the form of a link header (as described by RFC 8288), to share valid/invalid information with a client that knows to look for it.

The short version: link relations are a triple, this context has that relation to some target. You can use a registered link relation or define your own extension relation type.

A quick peek at the IANA registry suggests that either

• type
• status

could be suitable.

The link targets can be anything, really; one interesting possibility is to use as a target retrievable documentation that describes to a human what is going on.

So the signal that a resource is invalid could be a link to a document that explains what invalid means, and what (if anything) the client might do about it.

Link: </status/invalid>; rel="status"

Answer 3

It seems to me that this is basically a RPC. Consequentially it should be something like:

POST ResourceOrContextName/IsValid
Body:
{
   //resource goes here
}

• Post instead of Get, because the result can change on every call and we are not returning a resource,
• "IsValid" because that summarises the operation in english and implies a boolean response.
• Send the resource rather than the Id to avoid locking issues and avoid statefullness
• Resource or Context, because you might have more than one type of validity, valid for purchase, valid for return, whatever

Answer 4

“Valid” is a bit unfortunate as a name. Some people will think it’s the state of an entry in the database (related to the database), or it could be about the data itself. If you store passports in a database, or coupons, they could be valid or invalid.

If you want to avoid adjectives, call it “validity” with values “valid” and “invalid”. That also lets you add other values like “expired”, “reviewing” or whatever you need.