CODEWITHSUNDEEP
restapi
Neebz
Neebz

Reputation: 69

REST Api naming convention?

I have a simple question that I cannot find the answer to.

My colleague is currently making a REST Api for an application, and we have a call that simply checks some information, and returns either true or false. However, we do not know what to call this type of request, as it does not retrive any resources or insert anyhing, it simply checks some information passed into the query. As far as I can understand, a GET has to retrive a resource, which this call isn't doing

Upvotes: 1

Views: 1696

Answers (4)

cassiomolin
cassiomolin

Reputation: 130857

It's hard to tell by the level of details you provided your question. But if you need to check whether a resource exists or not, you can use HEAD. It's identical to GET, but it doesn't return a representation in the response payload: it returns just the status code and the response headers.

Consider the following request HEAD request:

HEAD /postal-codes/10001 HTTP/1.1
Host: example.org
Content-Type: application/json

It should return 200 for a resource that exists:

HTTP/1.1 200 OK
Content-Type: application/json

And 404 for a resource that doesn't exists:

HTTP/1.1 404 Not Found
Content-Type: application/json

Depending on your needs, you could address it with POST, which can be seen as a catch all verb.

For example, consider the following request and responses:

POST /postal-codes/validation HTTP/1.1
Host: example.org
Content-Type: application/json

{ "postal-code": "10001" }

HTTP/1.1 200 OK
Content-Type: application/json

{ "postal-code": "10001", "status": "valid" }

HTTP/1.1 200 OK
Content-Type: application/json

{ "postal-code": "10001", "status": "invalid" }

Upvotes: 1

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57204

As far as I can understand, a GET has to retrive a resource, which this call isn't doing

Technically, it is retrieving a resource; see Fielding

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource.

The resource, in this case, might not load an entity in your data model, but that's OK. Not all resources have to.

Technically, I think what you have there is a "function"; all of the information that you need to compute the result is present within the URI itself? Which would mean that, if the client knew how to do the computation (and had the compute resources available), then the client would be capable of doing the work for itself.

But there's nothing wrong with having a resource that is "the result of a function".

In some API, you'll see predicates (functions that return true/false) implemented as resources that only exist (more precisely, only have "representations") if the evaluation is true.

GET /predicate?true

204 No Content

GET /predicate?false

404 Not Found

The fact that you don't need to consider the resources "state" to compute the correct response to the query is an implementation detail hidden behind the uniform interface.

Upvotes: 1

Evert
Evert

Reputation: 99505

There might be a different way to express 'checking some information', and it's important to be a bit more specific as to what that means.

So lets take an arbitrary example. You're modelling blog posts and want to know if some blog post is set to 'draft'.

The 'draft' status can be its own resource, for example:

/posts/hello-world/is-draft

Doing a GET request on the is-draft resource can yield:

{
   "is-draft": true
}

So to model arbitrary things as resources, the best way to think about this is to look at the result of the operation as the 'representation' and the 'thing you want to know' as the URI.

Upvotes: 1

Pratik Dekate
Pratik Dekate

Reputation: 44

What I understand is, resource in this case is either true or false. While calling the API you will expect response either true or false on the basis of information processed by API server (status will be always 200). So a GET method is still suitable for this case. If you are not interested in response body and you want data like response code and header details, go with HEAD.

Upvotes: 3

Related Questions