I often refer back to Prakash’s great post on REST API Design, which describes reification (making abstract things concrete).
That’s called a method. It’s easy for Java developers like us to think this way, but it’s not RESTful design. Can you find a similar example in GitHub’s API?
Consistency is a good thing; however, consistently “special” isn’t as good of a thing.
These are more indicators that our design could be improved. Having resource that you can’t get is unexpected behavior in a REST API.
Yes. I understand. In RESTful design, paths are supposed to refer to resources and resources are not supposed to have more than one path to them. The pattern of
/some/path/:UUID is supposed to be the path to the resource with that UUID, so having two different paths ending in the same UUID is an indicator of a design problem.
Could we treat
/searchindex as a search index update request (or even rename it to
/searchindexupdate)? You could still implement essentially the same thing, but it would be:
which could also be supported as:
which would avoid the issues above, naturally allow for batch requests, and leave open the options in the future to interact with update requests (e.g., post a request to update 500 objects which returns
/searchindexrequest/:UUID, which is a resource that can be monitored for status updates).