Defining operations in REST API

Question

I am working on a message request which will have complete request details used to create a record in destination.

This integration create 3 different type of records (Order, shipment, invoice) at different times i.e. it will not always possible to create all at once, so I need to let the system know to create only certain requests.

My questions, what would be the best to way to add this information in request?

• Does it need to be in body of the request?

  {
     "OrderNumber": "1234", 
     "operation": [
       "orderentry",
       "shipment",
       "invoice"
     ]
  }
  

• Does it need to be in path?

   /Order/create?operation=orderentry
  

• Does it need to be in seperate object? say

   {
     "operation": [
       "orderentry",
       "shipment",
       "invoice"
     ],
     "request": {
       "OrderNumber": "1234", 
  
     }
  }
  

Answer 1

The effective uri of the request should identify the document that is being modified; the payload should be the document that describes the modification.

POST /home.html
Content-Type: text/plain

Bob, please fix the spelling error in the title.  Thanks.

/home.html identifies the document we are modifying; the body tells us about the modification that the client wants to make.

The uniform interface constraint ensures that everyone (servers, clients, intermediary components) all interpret this message the same way -- the semantics of the request are the same everywhere, as are the semantics of the response.

Note that we don't send the request to /home.html?edit or /home.html?operation=edit because those are two different resources (we know this, because the identifiers are different). By correctly identifying the resource we are modifying in the request, we make it clear to general purpose components what is going on, so that they can do intelligent things (like invalidating caches).

Whether or not the information needs to be in a "separate object" is a matter of schema design; HTTP really doesn't care what schemas you use in the documents that you are transferring over a network.

Answer 2

If you just want to use HTTP as a transport mechanism, then everything goes. If, on the other hand, you want to develop a truly RESTful API, you should learn about REST. As a start, consider the Richardson maturity model. I don't consider an API RESTful unless it's a level 3 API, but even at level 1, you should model the API as a set of resources.

Each resource should be identified by a unique URL, so that already rules out two of the three options in the OP.

The resources should be identified by their URL, but not as suggested. At level 2, actions are indicated by HTTP verbs (GET, POST, DELETE, etc.). Thus, to support creation of an order, I'd envision an HTTP request like this:

POST /orders HTTP/1.1
Content-Type: application/json
{
  "orderNumber": 1234
}

A successful request should result in a response in the 200 range (200 OK, 201 Created, etc.).

If instead you want to create a shipment resource, you could POST to a shipments collection resource:

POST /shipments HTTP/1.1
Content-Type: application/json
{
  "orderNumber": 1234
}

Resources like orders and shipments are typically called collection resources because they represent collections of other resources. They typically support only the POST and GET verbs, where GET would enumerate all the resources in the collection.

Each POST against a collection resource typically results in the creation of a 'sub resource' with its own address. For example, when you create an order, the created address might be /orders/1234. Such a resource would typically support GET, DELETE, and maybe PUT, but not POST.

I highly recommend Allamaraju Subrahmanyam's book RESTful Web Services Cookbook for anyone wanting to get into REST API design. It's easy to read and full of practical solutions.