I am trying to model APIs for

  • Create shipments
  • Fetch Available shipments (based on region preferences)
  • Accept shipments (allows logged in user to accept multiple shipments on first come first serve basis )
  • Allocate shipments (allows logged in user to allocate multiple shipments to driver, shipments must be accepted first)

What would the intuitive options for RESTFul API design for below scenarios? Does adding mine or my add any value or it is implicit that call is executed in the context of authenticated user?

Loading shipments This is straightforward by designing POST \shipments\

Available shipments

Option 1: \my\shipments
Option 2: \availableshipments
Option 3: \shipments?available=yes

Accept shipments

Option 1: \my\shipments\acceptance
Option 2: \acceptedshipments
Option 3: \shipments\acceptance

Verb: PUT


       "10000023",    "10000025",   "10000025"

Allocate shipments

Option 1: \allocatedshipments
Option 2: \shipments\allocated

Verb: PUT


"driverid": "12312",
"id" :  
       "10000023",    "10000025",   "10000025"

1 Answer 1


How would you do that as a website?

Would you tell your users to submit some magic content to some magic URI, or would you offer a webpage where there is a form the user can fill out and just submit?

For a RESTful API, you would describe the pages you have in your application through Media Types, and let the client navigate through the use-cases using links and forms on its own. In this case the client would not need to know URIs, HTTP Methods or what to submit beforehand, because all that is discovered on the fly.

I'm just saying that, because you (or other people reading) may be not aware, that is how it was supposed to work. If you don't want to do that, and just want endpoints that do things, return some data, and all of that is hardcoded into the clients, then I guess there's no real difference in any of those options. You have to read the documentation and hardcode the URIs into the client, or even generate it automatically. Would different URIs make any difference there?

  • This use case is not suitable for M2M(machine to machine/unattended) use case as there is human judgment required. This Api will be purpose built for User interface. Commented May 18, 2021 at 13:57
  • You mean it is built for humans? Why don't you use HTML then instead of JSON? Commented May 18, 2021 at 14:44
  • User interface is SPA(single page application) calling REST Apis using HTTP Verbs and JWT token based authentication. Commented May 19, 2021 at 15:58
  • None of that disqualifies HTML. I'm just wondering whether you're making it more complex than it needs to be. A lot of times you'll be forced to change both the SPA and Backend at the same time if you do it your way. That is something we want to avoid normally, unless there is a very good reason to the contrary. Commented May 20, 2021 at 7:41
  • yes, you are right, we are forced to change both the SPA and Backend at the same time. Can you elaborate - how this can be avoided? Commented May 23, 2021 at 12:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.