What is the use of 'Route' in Restangular functions oneUrl() and allUrl()

Question

That's the signature for oneUrl function: oneUrl(route, url)
And from the documentation:

oneUrl(route, url): This will create a new Restangular object that is just a pointer to one element with the specified URL.

To me, it seems useless to set Route when you are giving a url for the resource. Why does it exist in the argument list? Why is it mandatory? And how can it be used?

Answer 1

In my use of oneUrl I've found the route name is used to build the URL for subsequent PUT and DELETE operations. For example (pseudo code):

// "GET /api/v2/users/3/ HTTP/1.1" 200 184
var user = Restangular.oneUrl('myuser', 'http://localhost:8000/api/v2/users/3').get();
user.name = 'Fred';
// the following uses the route name and not the URL:
// "PUT /api/v2/myuser HTTP/1.1 404 100
user.put();

I was surprised by this behavior. I expected put() to use the same URL as get(); which would be helpful in my case.

My API uses absolute URLs within the JSON payloads to navigate to all related resources and I wanted to use oneUrl() to GET/PUT instances without recreating the routes in the JS code. But I'm pretty new to Restangular so I might not have the mental model correct.