5 ms·

> you'd build a REST application Nah, nerds would come out of the woodwork to inform you that what you've built is not a real REST.

by bushin 8y ago

criddell 8y ago
Yeah - there's always a HATEOAS comment somewhere and I've never really managed to figure out what that means beyond using URI's rather than a database IDs + some documented endpoint path to point to other resources.
- NoGravitas 8y ago
  This should help: http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.ht...
- JimDabell 8y ago
  It's pretty simple – the information a client needs to transition from one state to another needs to be encoded in the documents. So if you were to design a garage door opener, a non-REST specification might say something like: To get the door status, GET https://example.com/status To open the door, POST to https://example.com/open To close the door, POST to https://example.com/close A REST approach might use a document something like this: { "doorState": "closed", "actions": [ { "label": "Open the door", "href": "/open", "method": "POST" } ] } Then, upon a client performing an "Open the door" action, the server would then respond with a document like this: { "doorState": "open", "actions": [ { "label": "Close the door", "href": "/close", "method": "POST" } ] } …and vice-versa. So at any given point, the web service is describing to the client what the state is and how to transition to other states. There's quite a few different benefits to doing it this way – for instance, if you wanted to add a "Turn the garage light on" feature, you could just add the action into the API and clients would be able to use it without any changes whatsoever. Or if you wanted to disable an action, you'd simply remove it from the actions array and the client wouldn't present it to the user as an option. Want to A/B test different label text? You don't need any special A/B testing functionality in the client, just vary the responses you send to users and observe which actions they take. Want to translate into different languages? Just take a look at the Accept-Language header coming from the client and respond with the right label text. In practice, you'd want to use a vocabulary that's already out there like Hydra instead of coming up with your own format. But it can sometimes take a little time to get up to speed with them because they are necessarily quite flexible. But you can get most of the way there by simply thinking about it in terms of "the server tells the client what to do and how to do it". For something as simple as a garage door that you are certain will never need to change? The benefits REST brings probably aren't going to be worth much to you. But as the complexity of an API grows, the point at which it's easier to use REST than not arrives very quickly. If you want to read more about this, the best book I've found on the subject is RESTful Web APIs: http://restfulwebapis.com/ http://restfulwebapis.com/
  - criddell 8y ago
    The problem I have with that explanation is that it seems to assume the existence of a universal client. How many clients are examining responses and using that to build up a UI for actions with no anticipation of what those actions might be?
    - JimDabell 8y ago
      I don't see why you jumped to that conclusion. What about that JSON requires a universal client? It seems trivial to implement a personal "Garage Automation Client" based on that JSON that doesn't have to deal with anything else.
      - criddell 8y ago
        I might have this 100% backwards, but I've always thought the application state part of HATEOAS is entirely in the client. Does the server know anything about application state other than maybe implicitly through resource state?
        JimDabell 8y 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.
        criddell 8y ago
        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.
- olavk 8y ago
  HATEOAS is pretty simple - it is pretty much what you describe. Like a webpage which embed links to other webpages which you can then follow. The problem is people thinking HATEOS is a requirement for web services.
- dragonwriter 8y ago
  > there's always a HATEOAS comment somewhere and I've never really managed to figure out what that means beyond using URI's rather than a database IDs You know how browsers use URLs to find content and Content-Type to decide what to do with it, and links ib URLs in content (so as anchor tags in HTML) to find related content: that's HATEOAS in the original REST API.

> you'd build a REST application Nah, nerds would come out of the woodwork to inform you that what you've built is not a real REST.

by bushin 8y ago

> you'd build a REST application Nah, nerds would come out of the woodwork to inform you that what you've built is not a real REST.

criddell 8y ago

Yeah - there's always a HATEOAS comment somewhere and I've never really managed to figure out what that means beyond using URI's rather than a database IDs + some documented endpoint path to point to other resources.

NoGravitas 8y ago
This should help: http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.ht...
JimDabell 8y ago
It's pretty simple – the information a client needs to transition from one state to another needs to be encoded in the documents. So if you were to design a garage door opener, a non-REST specification might say something like: To get the door status, GET https://example.com/status To open the door, POST to https://example.com/open To close the door, POST to https://example.com/close A REST approach might use a document something like this: { "doorState": "closed", "actions": [ { "label": "Open the door", "href": "/open", "method": "POST" } ] } Then, upon a client performing an "Open the door" action, the server would then respond with a document like this: { "doorState": "open", "actions": [ { "label": "Close the door", "href": "/close", "method": "POST" } ] } …and vice-versa. So at any given point, the web service is describing to the client what the state is and how to transition to other states. There's quite a few different benefits to doing it this way – for instance, if you wanted to add a "Turn the garage light on" feature, you could just add the action into the API and clients would be able to use it without any changes whatsoever. Or if you wanted to disable an action, you'd simply remove it from the actions array and the client wouldn't present it to the user as an option. Want to A/B test different label text? You don't need any special A/B testing functionality in the client, just vary the responses you send to users and observe which actions they take. Want to translate into different languages? Just take a look at the Accept-Language header coming from the client and respond with the right label text. In practice, you'd want to use a vocabulary that's already out there like Hydra instead of coming up with your own format. But it can sometimes take a little time to get up to speed with them because they are necessarily quite flexible. But you can get most of the way there by simply thinking about it in terms of "the server tells the client what to do and how to do it". For something as simple as a garage door that you are certain will never need to change? The benefits REST brings probably aren't going to be worth much to you. But as the complexity of an API grows, the point at which it's easier to use REST than not arrives very quickly. If you want to read more about this, the best book I've found on the subject is RESTful Web APIs: http://restfulwebapis.com/ http://restfulwebapis.com/
- criddell 8y ago
  The problem I have with that explanation is that it seems to assume the existence of a universal client. How many clients are examining responses and using that to build up a UI for actions with no anticipation of what those actions might be?
  - JimDabell 8y ago
    I don't see why you jumped to that conclusion. What about that JSON requires a universal client? It seems trivial to implement a personal "Garage Automation Client" based on that JSON that doesn't have to deal with anything else.
    - criddell 8y ago
      I might have this 100% backwards, but I've always thought the application state part of HATEOAS is entirely in the client. Does the server know anything about application state other than maybe implicitly through resource state?
      - JimDabell 8y 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.
        criddell 8y ago
        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.
olavk 8y ago
HATEOAS is pretty simple - it is pretty much what you describe. Like a webpage which embed links to other webpages which you can then follow. The problem is people thinking HATEOS is a requirement for web services.
dragonwriter 8y ago
> there's always a HATEOAS comment somewhere and I've never really managed to figure out what that means beyond using URI's rather than a database IDs You know how browsers use URLs to find content and Content-Type to decide what to do with it, and links ib URLs in content (so as anchor tags in HTML) to find related content: that's HATEOAS in the original REST API.