RESTful client - how to process an external link?

Question

By RESTful best services there is the HATEOAS principle which told us that we should not allow the client to build resource URL-s. If we follow this principle, it will be pretty hard to share the current state of the client. For example if you have a REST service on the server, and you gets data via AJAX with a single page javascript client, then you will have 2 urls. One for the client state, and one for the result you got from the REST service. You can share only the client state with the use due to pushState... If somebody runs the client with a previously shared url, then her client won't know about the url of the REST service it should call, because the client cannot build URL-s, just receive from the REST service and utilize it.

For example:

• I browse the http://my.client.com
• the page gets the root resource from the http://my.api.com, and return a link
• the link contains the http://my.api.com/users url, with rel user collection
• after that the client displays a button with label: userlist
• I click on that button, the client get the data from the api, and prints the user list
• if I want to share the user list with my girlfriend, then I have to change the browser url from the client with pushState, for example from http://my.client.com to http://my.client.com/users
• after that I send that url to my girlfriend
• she copy-pastes that into her browsers address bar and presses enter. after that the client says a huge wtf, because - like John Snow - it knows nothing about what state that url means...

This problem can be solved, if we allow the client to build GET http://my.api.com/users from the url: http://my.client.com/users, but this won't be RESTful, because the client should not build api urls...

If I want to display a nested menu in the client, then that is another problem, because I don't want to send the whole menu tree in every answer. I could create a menu projection for every resource, or use the OPTIONS method, or a custom method to send that data, but that would be a pain in the back. This can be solved by following the rel=up links - got from the REST service - in series, but if I don't know from where should I follow, it will not work...

This problem occurs by google bots too...

How can I both solve this problem, and stay inside the boundaries of the HATEOAS principle?

Answer 1

Normally we don't want to share all of that information with anybody, so we cannot export all of that just the current page we are in.

There is nothing wrong with storing the whole resource on the client and then pushing it up to the server to change the state on the server. If you are worried your resources are getting too large though you could break the resources out a bit. So say you have an order resource and that needs to associate with an address. You don't need to put the address in the order resource, just a link to the address to use. The user can add or alter that address independently. So you might have something like

www.myapi.com/users/1234/shippingaddresses/default

And the client can PUT a new address to this resource. Then in the body of the order resource you can have a link to this resource

POST www.myapi.com/users/1234/orders
{
    ...order information...
    "shipping_address": "www.myapi.com/users/1234/shippingaddresses/default"
}

To be RESTful the client should not build that URL, it should have been given it by the server at some point in the recent past, possibly when the users is selecting which address to use. For example, in the previous step the client could have requested all addresses

GET www.myapi.com/users/1234/shippingaddresses

And presented the list of addresses to the user in a drop down list.