0

In the backend I have a method (function) that accepts an optional input of type date and finds the week that day falls in and return the start and end day of that week. an example, if input is 2020/04/14, it will return:

{
  "start" : "2020/04/13",
  "end": "2020/04/19"
}

I would like to expose this as a REST endpoint. I have been thinking of these two options:

    1. 
GET /week?date=2020/04/14
    2. 
POST /week?date=2020/04/14

However, I would like to know how should an endpoint like this be implemented based on REST architecture and common convention? it is calling a method in the backend and it is not working with a resource.

hamid
  • 2,033
  • 4
  • 22
  • 42

3 Answers3

3

A POST request usually is used to change data on the server, in fact to create a new entry (for example insert a new database row or save a certain entity).

A GET request usually is used to fetch some data, e.g. to read from a database without making changes.

So in this case, GET should be used.

Philipp
  • 520
  • 3
  • 7
  • what you mentioned is correct but it does not answer this question. in this example we are not dealing with any resource – hamid Apr 18 '20 at 19:26
  • @Sam You're certainly not making any changes to a resource, so that already completely rules out using a POST request. The other option you gave is GET and your description conceptionally sounds like a query (fetching some data, in this case the start and end date) although not dealing with an actual resource, GET should be used here because it conceptionally fits. The service consumer does not know if you use some algorithm to obtain the results or you have the answers stored in a database and you just query them. Look at the problem from the viewpoint of the service consumer. – Philipp Apr 18 '20 at 19:44
2

in this example we are not dealing with any resource

Resource, in the context of REST, means something specific. Here is how Fielding describes resource:

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.

So from the framework of REST, it is perfectly reasonable to say that /week?date=2020/04/14 identifies a resource whose representation describes a calendar week.

Since the HTTP request in this case has effectively read only semantics (aka "safe" semantics) -- we're not expecting the server to change in any way -- the natural fit for this request would be to use GET.

GET /week?date=2020/04/14

As a general rule, anything that is just returning the result of a calculation should use GET, with the parameters provided by the client encoded into the identifier of the resource (as we did with GET forms on the web).

The exception to this are those cases where the parameters are so large/numerous that your queries get crippled by de facto limits on URI length. In those cases, you use POST, sacrificing easy caching for getting the job done at all.

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
0

POST is used when you want to put a body in there with some 'heavy' load. So in this case, I think GET is fitting well for your needs.

vladtkachuk
  • 656
  • 4
  • 13
  • It's a bit more complicated than "if there is a body you should use POST", check out some REST guidelines like [this one](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design) – rdas Apr 18 '20 at 21:43