我应该为REST服务使用哪种HTTP方法？

Question

You might have seen many post related to this title. But, I think, I have a different case where I need help. I tried to go thru several threads for my question but could not find any specific answer that I can go with confidence.

To explain, I want to publish a RESTful API that performs typical GET operation based on provided input details. This API is idempotent in nature and does not create, update or delete any resource. So, my ideal choice should be to use HTTP GET method in this case.

However, making things complex, my API will need a big JSON object with details as a part of the request to derive required information for the response. It is not advisable to put that JSON string in the request URI. Hence, I have to put that in request body itself. But, HTTP GET does not consider request body content. And, I don't want to (or don't know if I should) use HTTP POST or PUT for this API as the API is idempotent and does not create/modify any resource.

For now, I am more inclined towards using HTTP OPTIONS for this purpose, but I am not sure if this is something I should do considering RESTful standardization.

So, what do you suggest? Is it an acceptable usecase to use POST or OPTIONS in this case? Or, I should do something else?

For reference, below is the dummy sample of the request data object.

{
"parametersList": {
    "itemRange": {
        "code": "11",
        "start": 100683,
        "end": 168003
    },
    "dateRange": {
        "startDate": "2017-10-01",
        "endDate": "2017-10-31"
    },
    "market": {....},
    "startTimeRange": {...},
    "endTimeRange": {....},
    "serviceType": {....},
    "segmentType": {....},
    "daysOfWeek": {
        "days": ["MON", "WED", "THU", "FRI", "SAT", "SUN"]
    },
    "itemNumber": 0
}
}

The {...} in above example represents internal object structure that may vary based on the data.

Answer 1

In such cases you should use POST. In general POST is used if no other method is applicable. OPTIONS has another purpose and cannot be used here.

POST is for example also used for large search queries where you specify search terms in the body

Another good example for using POST instead of GET is when you are sending sensitive data in the request.

also have a look at this article

and this question

Answer 2

Go for POST, even if you manage to get it done with GET(creating a URI) its not the optimal solution as there might be cases when your GET request URL can become too long.

Moreover I didn't find any viable source discouraging the use of POST for querying with a valid reason.

POST(with some other security measures) is used for authentication as well, which does not create/modify any resource. So using it for your problem shall not be a bad practice.

Answer 3

This is an interesting one because of your requirement to send a big JSON object.

A REST API endpoint that gets a resource should always use a GET endpoint with GET parameters. Is there a specific reason why you are trying to send a JSON object rather than sending parameters?

In the case that you insist on sending a JSON object, I have found examples of existing code that base64 encode the JSON object and then add it to a GET parameter. However please note that if you try to send a massive JSON object you could have issues with URL length. But it should never come to that. GET parameters on a restful API should always be simple and short. If you are sending too much data then there's something wrong with the design of the REST API and it needs to be thought through more carefully.