Comment by JimDabell
7 years ago
The server tells the client about the state through the hypertext documents it sends it. The client then transitions to a new state by performing an action described in that document. Hence: Hypertext/Hypermedia as the engine of application state (HATEOAS).
I'm still not grasping why you think the API above needs some kind of universal client though. You can implement a very simple client for that extremely quickly. All you need to do is loop over the actions and render a button for each one using the provided label. Then when the button is clicked/tapped, you perform the action described and the response will be the next state.
I'm not saying it needs a universal client, just that it's the only real reason I can think of for including all of that.
For example, say we are writing a client to do something with Fitbit data. Step one wouldn't be to send a GET to the root to find out what actions are possible, would it? We might find out they have APIs for tracking vehicle mileage but I don't want that in my client - I just want to graph the hours I've been sleeping. So I'm going to Fitbit ahead of time knowing what I want to do.
If you were going to craft a client UI based entirely off the server responses, you are going to recreate the Gopher experience, and nobody wants that.
> just that it's the only real reason I can think of for including all of that
Having done a fair bit of HATEOAS driven APIs, but one benefit of the above is that it allows you to change "/open" to "https://otherservice.com/open" if needed and applications will start hitting the correct endpoint. Sure you can solve that with redirects or a reverse proxy config entry, but in my limited experience it is quite convenient to specify that in the response.
One good example is something you've probably already done: Download URLs. Instead of having clients build "https://cdn.photoservice.com/photos/12341231/download" whenever they want to download a raw file, they instead hit "https://api.photoservice.com/photos/12341231" which has a "download_url" in the response. They then fetch the file from that url. In my experience that download_url is region specific, or it has query params that AB test different resolutions, or it's AB testing different CDNs, etc.
I hope that benefit is clear enough. Now think about how those same benefits can be applied to a wider range of API endpoints. That might seem like overkill to do everywhere, and probably is, but it certainly has benefits in the right situations.
> I'm not saying it needs a universal client, just that it's the only real reason I can think of for including all of that.
I already gave several examples of reasons why you would do it this way in my earlier comment.
Why have we leapt from the garage remote example to a FitBit that tracks vehicle mileage? I don't see why you keep leaping to "it must handle everything everywhere". Stop thinking about handling everything under the sun – we're talking about a garage remote.
> If you were going to craft a client UI based entirely off the server responses, you are going to recreate the Gopher experience, and nobody wants that.
REST is a distillation of the principles that make the web work. Can you see the parallels with how HTML forms work? Browsers don't need to know that contact forms need to be POSTed to /contact, the server sends the client a document describing the action to take.
Okay - so to put my question in terms of the garage remote example, say the API offered is_open, open_door, and close_door functions.
A "dumb" client that is configured by the server is going to include all three. Image a developer that only wants the UI to be a toggle that mimics an actual hardware button? That would require some a priori knowledge of what the API supports. The list of actions is perhaps useful for the developer before they write their code. But then version 2 of the API may remove the close function and expand open to accept a value between 0 and 1. The client is going to need to be updated and the action list will again be useful for an afternoon.
> Can you see the parallels with how HTML forms work?
Okay - now that's a fantastic question that has me reconsidering everything I said. I think what's special about HTML forms is that the browser is the universal client. I have to think about that more though.
I appreciate you trying to help me see the light here. This is something that has bothered me since I first started reading about REST.
3 replies →