HACKER Q&A
📣 sethammons

REST Custom Method: vs. /


Please help me understand why we would want to do this. At work, we've adopted this guide to specify an action on a resource:

https://cloud.google.com/apis/design/custom_methods

Instead of /api/job/:foo/cancel, they use /api/job/:foo:cancel.

I imagine URL parsers and routers have a much easier time with the former compared to the later. In the later, I imagine most people are having to do additional tokenizing to enable further routing. I can't think of a redeeming factor.

Thanks

  👤 calrain Accepted Answer ✓
From the page you linked:

The reason to use : instead of / to separate the custom verb from the resource name is to support arbitrary paths. For example, undelete a file can map to POST /files/a/long/file/name:undelete

At the end of the day there is no 'right' way to build an URI rule set for an API, it's a hill I will die on.

Everyone has their own reasons and limitations, heck, some people get you to use POST over GET because of security and header limitations of GET.

It's important to get your solution running and that means following their rules.

If you do set your own rules for a URI naming scheme, just make sure you try to follow those rules consistently. Then at least your flavor of madness will be consistent :)