REST actions and URL API design considerations

Question

I'm building a inventory management system and I'm busy designing (thinking) of the API and my REST implementation.

I have the following resources and on the resource you can perform many actions/operations. Each operation will modify the resource and in some cases create a new resource and also create history or transactions.

I'm looking for some input from experts in regards to useability and acceptability in regards to URL and resource design. The gotchas and real world examples, any opinion or criticism welcome.

My concerns are that the whole application might be develop around this one big resource? My backend stack will be C# and servicestack framework and for frontend I'll be using HTML and AngularJS. Not that it makes a difference.

Scenario 1. Typical operation will be:

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /inventory/{id}/pick
PUT  /inventory/{id}/receive
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /inventory/{id}/transfer
POST /inventory/{id}/return
POST /inventory/{id}/adjustment


{
  "userID": "",       //who is doing the actions (all)
  "tolocationID": "", //new location for inventory (move/takeon/pick/receive/transfer/return)
  "qty": "",          //qty (pick/receive/takeon/transfer/return)
  "comment": "",      //optional for transaction (all)
  "serial": "",       //(takeon/receive)
  "batch": "",        //(takeon/receive)
  "expirydate": "",   //(takeon/receive)
  "itemCode": "",     //(takeon/receive)
  "documentID": "",   //(pick/receive/return/transfer)
  "reference" :"",    //(all)
  "UOM" :"",          //(all)
  "reference" :"",    //(all)
}

Is this acceptable in regards to standards. The other approach might be.

Scenario 2.

POST /inventory/{id}/move
POST /inventory/{id}/scrap
PUT  /inventory/{id}/takeon
POST /document/{id}/pick     //**document**
PUT  /document/{id}/receive  //**document**
POST /inventory/{id}/hold
POST /inventory/{id}/release
POST /document/{id}/transfer  //**document**
POST /document/{id}/return    //**document**
POST /inventory/{id}/adjustment

and then to change the resources.

Scenario 3. in my opinion wrong

POST /transaction/move/{...}
POST /transaction/scrap/{...}
PUT  /transaction/takeon/{...}
POST /transaction/pick/{...}  
PUT  /transaction/receive/{...} 
POST /transaction/hold/{...}
POST /transaction/release/{...}
POST /transaction/transfer/{...}  
POST /transaction/return/{...}
POST /transaction/adjustment/{...}

Any comments welcome, not looking for answer but more advice on design considerations?

Thanks for taking the time reading this entry!

Answer 1

I have the following resources and on the resource you can perform many actions/operations. Each operation will modify the resource and in some cases create a new resource and also create history or transactions.

Fundamental to the REST architectural schema is the idea of using the HTTP verbs as the only verb, and not including verbs in your URLs. In your shoes, I would consider reworking your system to remove the verbs. It's hard to suggest a design without actually knowing what any of the verbs mean, but perhaps something closer to:

GET /inventory/{id}
PUT /inventory/{id} -- update with new location 
PUT /inventory/{id} -- update with new status (scrapped)

etc .. That's a more RESTful approach. Many of these actions look like they're really just PUTs that update multiple properties of the resource, such as location, quantity, comment field, etc. And perhaps scrap is DELETE? Hard to tell.

Another option would be to use POST, where the body includes the instructions for how to operate on the inventory item:

POST /inventory-transactions/{id}
{
    "action": "takeon",
    "newLocationId": 12345,
    ...
}

This gives you a lot of traceability, because every operation can now be tracked as a resource. The down side is a lot of complexity around the endpoint.

You can also break out some of the "verb" operations into resources:

POST /returned-inventory
{
    "inventoryId": 12345,
    "documentId": 67890,
    "comment": "Busted up",
    ...
}

This lets you easily look at inventory items by their status, which may or may not be helpful. You could, for instance, call GET /returned-inventory?documentId=67890 to get back all the returned items from the same document.

Hopefully there's some food for thought in there. It's really not going to be possible for anybody to tell you the "right" thing to do without knowing your business requirements in greater detail.

Answer 2

"Restful Objects", which defines a RESTful API, states that actions are valid.

Available actions can be discovered, enabled/disabled, and can give 'disabled reason' feedback.

Actions are 'invoked' using GET (query), PUT (idempotent), or POST(non idempotent)

Restful Object Spec (page C-125)