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, undel

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 :)