architecture - 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

Short answer:

Use actions at the end of the url to change state.

Github does it like this to star a gist: PUT /gists/:gist_id/star

Explained here https://developer.github.com/v3/gists/#star-a-gist

Long Answer:

Your objective is making your applications effortless to use an intuitive. Your users should use your app in the simplest possible way. Your users should not suffer the limitations or hard guidelines of the technologies you use.

So actions and operations are inherently not resources, but actions over resources. So they will not respond to a "resource to URI mapping" like REST is.

But you can use the best of REST, and still the best of URIs, combining both.

Remember:

The technology should work for you, and not you for the technology.

If you become an slave of technology, you will end up creating unusable applications or using ugly technologies like XML or Java Home and Remote interfaces, so you end up writing 5 files to create a hello world application.

BEWARE of the "shiny object syndrome". Google it.

Not because a technology is new or is "the new way of doing things", it means that is a good technology or you need to get distracted and let aside all other technologies to succumb to REST.

Take what you need from the technology and then make the technology work for you.

Using REST api does not mean you need to discard the capabilities of the URL and URI technologies.

References: https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful