REST JSON API design

Question

For a Order Management Application, i need to design RESTful APIs which works with JSON.

I would prefer my APIs are like these, whereby request/response contains JSON:

Order Search API

API:    /orders/search
            {
                custname: "john",
                orderdate: "10-jun-2013"
            }
     Response:
           {
             orders:[
               {
                 orderid:234234,
                 orderstatus: NEW,
                 customer: "john"
               }
             ]
           }

Order Update API

 API:   /orders/343455        
 Request Body:
   {
            orderstatus: "DELIVERED",
            recepient: "joe"        
   }
 Response:
   {
      status: ERROR,
      message: "Order does not exist"
   }

Question:
1. How can i send JSON in a GET request (as in Order Search API).
2. I am even thinking of making every request a POST request, with JSON request in body, suggesting what the operation is - but then would this still be REST (perhaps 'RESTful Web-Service' or 'REST like Service' )?
3. I think its important for me to send JSON in most requests, that way my APIs implementations do not undergo much changes, just becz i added removed attribs to JSON message.
4. Are there any examples of how other people have done it, especially returning error messages.

Any thoughts?

score 0 · Answer 1 · edited Oct 07 '21 at 06:16

How can i send JSON in a GET request (as in Order Search API).

To my knowledge, HTTP 1.1 does NOT explicitly forbid a request body for a GET method.

However, opinions whether this is recommended differ.

The GET request should (must) be idempotent, however - especially in a REST context, and in order to allow caching.

See also this question on SO HTTP GET with request body and many others.

If you cannot specify a request body in a GET method, for whatever reason, you need to include the parameters in the URL query - properly encoded (which is a pain).

I am even thinking of making every request a POST request

I wouldn't do that. Web service frameworks expect certain types of requests to be performed with the corresponding HTTP method. It's against REST, for example a POST request which would be actually a GET will not be cached. That's against HTTP, too.

REST JSON API design

1 Answers1