9 ms·

Discoverability by whom, exactly? Like if it's for developer humans, then good docs are better. If it's for robots, then _maybe_ there's some value... But in r

Discoverability by whom, exactly? Like if it's for developer humans, then good docs are better. If it's for robots, then _maybe_ there's some value... But in reality, it's not for robots. HATEOAS solves a problem that doesn't exist in practice. Can you imagine an API provider being like, "hey, we can go ahead and change our interface...should be fine as long as our users are using proper clients that automatically discover endpoints and programmatically adapt accordingly"? Or can you imagine an API consumer going, "well, this HTTP request delivers the data we need, but let's make sure not to hit it directly -- instead, let's recursively traverse a graph of requests each time to make sure this is still the way to do it!"

naasking 1y ago
The problems do exist, and they're everywhere. People just invented all sorts of hacks and workarounds for these issues instead of thinking more carefully about them. See my posts in this thread for some examples: https://news.ycombinator.com/item?id=44509745 https://news.ycombinator.com/item?id=44509745
ivan_gammel 1y ago
You have got it wrong. Let's say I build some API with different user roles. Some users can delete an object, others can only read it. The UI knows about the semantics of the operations and logical names of it, so when UI gets the object from server it can simply check, if certain operations are available, instead of encoding the permission checking on the client side. This is the discoverability. It does not imply generated interfaces, UI may know something about the data in advance.
- tacone 1y ago
  That's actually an interesting take, thank you.
- shadowgovt 1y ago
  How does the UI check if certain operations are available?
  - troupo 1y ago
    OPTIONS https://datatracker.ietf.org/doc/html/rfc2616 https://datatracker.ietf.org/doc/html/rfc2616 More links here: https://news.ycombinator.com/item?id=44510745 https://news.ycombinator.com/item?id=44510745
    - notpushkin 1y ago
      Or probably just an Allow header on a response to another query (e.g. when fetching an object, server could respond with an Allow: GET, PUT, DELETE if the user has read-write access and Allow: GET if it’s read-only).
      - 9dev 1y ago
        That’s a neat idea actually, I think I’ll need to read up on the semantics of Allow again…. There is no reason you couldn’t just include it with arbitrary responses, no?
        notpushkin 1y ago
        I don’t see why not!
    - ivan_gammel 1y ago
      It’s something else. List of available actions may include other resources, so you cannot express it with pure HTTP, you need a data model for that (HAL is one of possible solutions, but there are others)
      - troupo 1y ago
        With HATEOAS you're supposed to return the list of available actions with the representation of your state. Neo4j's old REST API was really good about that. See e.g. get node: https://neo4j.com/docs/rest-docs/current/#rest-api-get-node https://neo4j.com/docs/rest-docs/current/#rest-api-get-node
- svieira 1y ago
  This is actually what we do at [DAYJOB] and it's been working well for over 12 years. Like any other kind of interface indirection it adds the overhead of indirection for the benefit of being able to change the producer's side of the implementation without having to change all of the consumers at the same time.
- motorest 1y ago
  > You have got it wrong. Let's say I build some API with different user roles. Some users can delete an object, others can only read it. The UI knows about the semantics of the operations and logical names of it, so when UI gets the object from server it can simply check, if certain operations are available, instead of encoding the permission checking on the client side. Have you ever heard of HTTP's OPTIONS verb? https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/OPTIONS https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/... Follow-up trick question: how come you never heard of it and still managed quite well to live without it?
  - ivan_gammel 1y ago
    Maybe you should reconsider the way you ask questions on this forum. Your tone is not appropriate and the question itself just demonstrates that you don't understand this topic. Yes, I'm aware of this header and know the web standards well enough. In hypermedia API you communicate to client the list of all operations in the context of the resource (note: not ON the resource), which includes not only basic CRUD but also operations on adjacent resources (e.g. on user account you may have an operation of sending a message to this user). Yes, in theory one could use OPTIONS with a non-standard response body to communicate such operations that cannot be expressed in plain HTTP verbs in Allow header. However such solution is not practical, because it requires an extra round trip for every resource. There's a better alternative, which is to provide the list of operations with the resource using one of the common standards - HAL, JSON-LD, Siren etc. The example in my another comment in this thread is based on HAL. If you wonder what is that, look no further than at Spring - it does support HAL APIs out of the box from quite a long time. And of course there's an RFC draft and a Wikipedia article (https://en.wikipedia.org/wiki/Hypertext_Application_Language https://en.wikipedia.org/wiki/Hypertext_Application_Language).
marcosdumay 1y ago
> If it's for robots, then _maybe_ there's some value... Nah, machine readable docs beat HATEOAS in basically any application. The person that created HATEOAS was really not designing an API protocol. It's a general use content delivery platform and not very useful for software development.

naasking 1y ago

The problems do exist, and they're everywhere. People just invented all sorts of hacks and workarounds for these issues instead of thinking more carefully about them. See my posts in this thread for some examples: https://news.ycombinator.com/item?id=44509745 https://news.ycombinator.com/item?id=44509745

ivan_gammel 1y ago

You have got it wrong. Let's say I build some API with different user roles. Some users can delete an object, others can only read it. The UI knows about the semantics of the operations and logical names of it, so when UI gets the object from server it can simply check, if certain operations are available, instead of encoding the permission checking on the client side. This is the discoverability. It does not imply generated interfaces, UI may know something about the data in advance.

tacone 1y ago
That's actually an interesting take, thank you.
shadowgovt 1y ago
How does the UI check if certain operations are available?
- troupo 1y ago
  OPTIONS https://datatracker.ietf.org/doc/html/rfc2616 https://datatracker.ietf.org/doc/html/rfc2616 More links here: https://news.ycombinator.com/item?id=44510745 https://news.ycombinator.com/item?id=44510745
  - notpushkin 1y ago
    Or probably just an Allow header on a response to another query (e.g. when fetching an object, server could respond with an Allow: GET, PUT, DELETE if the user has read-write access and Allow: GET if it’s read-only).
    - 9dev 1y ago
      That’s a neat idea actually, I think I’ll need to read up on the semantics of Allow again…. There is no reason you couldn’t just include it with arbitrary responses, no?
      - notpushkin 1y ago
        I don’t see why not!
  - ivan_gammel 1y ago
    It’s something else. List of available actions may include other resources, so you cannot express it with pure HTTP, you need a data model for that (HAL is one of possible solutions, but there are others)
    - troupo 1y ago
      With HATEOAS you're supposed to return the list of available actions with the representation of your state. Neo4j's old REST API was really good about that. See e.g. get node: https://neo4j.com/docs/rest-docs/current/#rest-api-get-node https://neo4j.com/docs/rest-docs/current/#rest-api-get-node
svieira 1y ago
This is actually what we do at [DAYJOB] and it's been working well for over 12 years. Like any other kind of interface indirection it adds the overhead of indirection for the benefit of being able to change the producer's side of the implementation without having to change all of the consumers at the same time.
motorest 1y ago
> You have got it wrong. Let's say I build some API with different user roles. Some users can delete an object, others can only read it. The UI knows about the semantics of the operations and logical names of it, so when UI gets the object from server it can simply check, if certain operations are available, instead of encoding the permission checking on the client side. Have you ever heard of HTTP's OPTIONS verb? https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/OPTIONS https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/... Follow-up trick question: how come you never heard of it and still managed quite well to live without it?
- ivan_gammel 1y ago
  Maybe you should reconsider the way you ask questions on this forum. Your tone is not appropriate and the question itself just demonstrates that you don't understand this topic. Yes, I'm aware of this header and know the web standards well enough. In hypermedia API you communicate to client the list of all operations in the context of the resource (note: not ON the resource), which includes not only basic CRUD but also operations on adjacent resources (e.g. on user account you may have an operation of sending a message to this user). Yes, in theory one could use OPTIONS with a non-standard response body to communicate such operations that cannot be expressed in plain HTTP verbs in Allow header. However such solution is not practical, because it requires an extra round trip for every resource. There's a better alternative, which is to provide the list of operations with the resource using one of the common standards - HAL, JSON-LD, Siren etc. The example in my another comment in this thread is based on HAL. If you wonder what is that, look no further than at Spring - it does support HAL APIs out of the box from quite a long time. And of course there's an RFC draft and a Wikipedia article (https://en.wikipedia.org/wiki/Hypertext_Application_Language https://en.wikipedia.org/wiki/Hypertext_Application_Language).

marcosdumay 1y ago

> If it's for robots, then _maybe_ there's some value... Nah, machine readable docs beat HATEOAS in basically any application. The person that created HATEOAS was really not designing an API protocol. It's a general use content delivery platform and not very useful for software development.