RESTful Resource URI/URL Naming – the missing piece

There are a lot of tutorials on the internet about RESTful URI/URL naming conventions – a good example is this one. If you are building modern web apps (which might make use of REST) you should build modern URLs. Bad URLs not only look ugly, they are definitely not useful in regards to search engine optimization.

Nevertheless all of them (didn’t find a single one which has it) have a missing piece which is needed and I have often seen done wrong. On the one hand it is not directly about REST on the other hand it is required to build all of this. But first a quick summary what you can find everywhere:

You are building the website example.tld which has customers. Customers can be viewed/read, added, edited/updated and deleted. So you are needing those URLs and requests:

Adding: POST example.tld/customers

Viewing/reading: GET example.tld/customers/1234 (1234 represents the customer id)

Editing/updating: PUT example.tld/customers/1234

Deleting: DELETE example.tld/customers/1234

This can be also done with some kind of hierarchy: example.tld/customers/1234/orders/5678

I think this makes the naming convention clear. The ids can also be exchanged with a unique readable URL for SEO friendliness:

example.tld/customers/david

Or better combining both versions like stackoverflow does it:

example.tld/customers/1234/david

This gives you the advantage to only have the id as an internal identifier, plus a readable url, but this URL can be easily exchanged and doesn’t have to be unique.

What is the missing piece? The URL under which the user can add a new customer or edit an existing one.

What I often see and you should not do is something like this:

GET example.tld/addcustomers

GET example.tld/edit_customers/1234

GET example.tld/customers_add

This kills the complete convention you’re following.

What you should do instead:

GET example.tld/customers/add

GET example.tld/customers/1234/edit

Like this the URL convention is not broken, it makes totally sense and does not mess anything up.