RESTful Resource Naming
Yesterday I had an interesting discussion with a colleague of mine about the routes and HTTP verbs we configured for our Web API operations. Being a code purist I liked the idea of having the URIs as RESTful as possible. But many operations of our software just didn't fit in, and it felt quite inconsistent.
The big question: should we hang on to the elegant resource naming of a RESTful API, or go our own way?
Why REST?
I'm not going to tell about the details of REST and RESTful API's. Many other resources like RestAPITutorial.com do a far better job at that than me. What's important for us in REST is the way it can deliver an understandable, easy consumable Web service API. We work with 3rd party developers, and by allowing them (and ourselves) to easily consume our API means saving time in both development and maintenance.
REST seems to have gained a lot of popularity over the last couple of years. Coming from WCF I find it a big improvement using ASP.NET Web API. Both have their pros and cons obviously, and one does not replace the other. How to configure your applications URIs (i.e. resource naming) is just one of the architectural constraints REST describes. But a very important one.
Having a RESTfull API means dividing up your system into resources. Resources represent pieces of information, like a User or Order. By using the verbs GET, PUT, POST, etc you can execute an action on a resource. This resource based style does look like a nice way of consuming an API over HTTP. Back in 1999.
It's 2016
And that's exactly the problem. REST was developed in 1996-1999, back then it was a whole different World Wide Web. Using POST or DELETE back then meant adding or deleting files like index.html or order.xml.
When REST was developed, resources were mostly just plain files.
And it did the job well back then. Now it's 2016: the vast majority of web applications are not simple collections of resources anymore. Resources are now heavily influenced by workflows and processes. An operation is now more task-based, with a far more specific input and output than passing the resource itself as data container.
So, no RESTful resource naming?
For the majority of modern web applications probably not. It would make sense if the application is really resource based. Like having no projection of data, specific tasks or custom workflows. It's all about what you're trying to achieve. Choose your resource/operation naming convention, and do apply it consistently.
RESTful resource naming just doesn't fit nicely for task-based web applications. Having frameworks like Swagger and use of GET- and POST-verbs is our way of naming our tasks. GET's for Queries, POST's for Commands.