7 ms·

I am not sure I follow his point about why HATEOAS is not practical, but I know that I have been able to make it work in my own REST APIs using content types. I

I am not sure I follow his point about why HATEOAS is not practical, but I know that I have been able to make it work in my own REST APIs using content types. I only return JSON if the Accept header specifies "application/json". (Which is probably what you should be doing anyhow.) I usually also allow an HTML fragment response for the "text/html-fragment" Accept type. The default response type (or if "text/html" is explicitly requested in the Accept header) is the HTML fragment data wrapped in document markup with any forms necessary to expose all functionality in the browser (without JavaScript, but just enough CSS to make it pleasant.) It takes more work, but it not only is the best documentation, you can point the href property of JavaScript click handled hyperlinks right to the REST URIs for proper fallback.

icebraining 13y ago
Content types and HATEOAS are orthogonal properties, I'm not sure how you made the latter work using the former?
- protonfish 13y ago
  Agreed, I am just trying to guess where the author is confused and reply in a useful manner. I am guessing that too many so-called "REST APIs" return JSON response bodies without explicitly requesting them in the Accept request header. By simply using the Accept header how it is meant to be used, you can return HATEOAS, JSON, XML or whatever format you want specifically designed for the target client.
  - icebraining 13y ago
    What does it mean to "return HATEOAS"? HATEOAS is an architectural contrainst, not a format.
    - protonfish 13y ago
      True. What I meant was a document that exposes all functionality of the network resource using hypermedia. I did not think that all responses had follow HATEOAS.) Some response should be OK returning partial data or limited functionality as long as something discoverable is explicit and comprehensive.
- dragonwriter 13y ago
  > Content types and HATEOAS are orthogonal properties, I'm not sure how you made the latter work using the former? They aren't orthogonal. Content-types are central to HATEOAS: From one of the key descriptions [1] of the HATEOAS constraint on REST: A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.] [1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
  - icebraining 13y ago
    That's media types. I was referring to the strings used in content-type, the HTTP header. You obviously need to support some media type, otherwise how would you represent a resource? But you don't need to support the Content-Type header to have HATEOAS.
    - dragonwriter 13y ago
      > That's media types. I was referring to content-type, the HTTP header. You obviously need to support some media type, otherwise how would you represent a resource? But you don't need to support the Content-Type header to have HATEOAS. If you are doing a REST architecture with a protocol other than HTTP, sure. But since the Content-Type header is the mechanism by which HTTP communicates media types, and since in-band, rather than out-of-band, communication of resource locations and media types is essential to HATEOAS, the Content-Type header is a pretty important mechanism in HATEOAS when using HTTP.
      - icebraining 13y ago
        file document document: HTML document, UTF-8 Unicode text You can distinguish between media types without using the Content-Type header or out-of-band communication. In fact, there's a (non-standard) header for preventing some browsers from replacing the Content-Type value with their own guess. It's obviously useful, especially for distinguishing between similar media types (e.g. JSON document with different schemas), but not necessary for HATEOAS.
veesahni 13y ago
HATEOAS is first and foremost about the API being self describing. Quoting from wikipedia: "A REST client enters a REST application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server."
- protonfish 13y ago
  I would disagree and say it is first and foremost about using hypermedia as the engine of application state.
brown9-2 13y ago
Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Does the JSON representation of a Employee object returned URLs as a part of the body for the resource addresses for any "child" objects? I don't think it can be considered HATEOAS if the answer to either is no.
- protonfish 13y ago
  Of course not - it is called HYPERMEDIA as the engine of application state (not JSON.) That's why it's not called JATEOAS. The information you are asking for sounds more appropriate in an OPTIONS request.
  - dragonwriter 13y ago
    > Of course not - it is called HYPERMEDIA as the engine of application state (not JSON.) If the answer to those questions is no (whether the format of the response is JSON or anything else), then you aren't using hypermedia as the engine of application state.
- SilasX 13y ago
  >Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Why, no, it doesn't, because it takes 3 parameters, each of which can take 10,000 possible values, and I don't want to transmit a trillion options every time someone pings the root. I mean, I considered documenting how to pass the parameters on a client's first entry but the HATEOAS crowd told me I was just re-creating RPC, and I agreed. So no HATEOAS.
  - deleted 13y ago
    [deleted]

icebraining 13y ago

Content types and HATEOAS are orthogonal properties, I'm not sure how you made the latter work using the former?

protonfish 13y ago
Agreed, I am just trying to guess where the author is confused and reply in a useful manner. I am guessing that too many so-called "REST APIs" return JSON response bodies without explicitly requesting them in the Accept request header. By simply using the Accept header how it is meant to be used, you can return HATEOAS, JSON, XML or whatever format you want specifically designed for the target client.
- icebraining 13y ago
  What does it mean to "return HATEOAS"? HATEOAS is an architectural contrainst, not a format.
  - protonfish 13y ago
    True. What I meant was a document that exposes all functionality of the network resource using hypermedia. I did not think that all responses had follow HATEOAS.) Some response should be OK returning partial data or limited functionality as long as something discoverable is explicit and comprehensive.
dragonwriter 13y ago
> Content types and HATEOAS are orthogonal properties, I'm not sure how you made the latter work using the former? They aren't orthogonal. Content-types are central to HATEOAS: From one of the key descriptions [1] of the HATEOAS constraint on REST: A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.] [1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
- icebraining 13y ago
  That's media types. I was referring to the strings used in content-type, the HTTP header. You obviously need to support some media type, otherwise how would you represent a resource? But you don't need to support the Content-Type header to have HATEOAS.
  - dragonwriter 13y ago
    > That's media types. I was referring to content-type, the HTTP header. You obviously need to support some media type, otherwise how would you represent a resource? But you don't need to support the Content-Type header to have HATEOAS. If you are doing a REST architecture with a protocol other than HTTP, sure. But since the Content-Type header is the mechanism by which HTTP communicates media types, and since in-band, rather than out-of-band, communication of resource locations and media types is essential to HATEOAS, the Content-Type header is a pretty important mechanism in HATEOAS when using HTTP.
    - icebraining 13y ago
      file document document: HTML document, UTF-8 Unicode text You can distinguish between media types without using the Content-Type header or out-of-band communication. In fact, there's a (non-standard) header for preventing some browsers from replacing the Content-Type value with their own guess. It's obviously useful, especially for distinguishing between similar media types (e.g. JSON document with different schemas), but not necessary for HATEOAS.

veesahni 13y ago

HATEOAS is first and foremost about the API being self describing. Quoting from wikipedia: "A REST client enters a REST application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server."

protonfish 13y ago
I would disagree and say it is first and foremost about using hypermedia as the engine of application state.

brown9-2 13y ago

Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Does the JSON representation of a Employee object returned URLs as a part of the body for the resource addresses for any "child" objects? I don't think it can be considered HATEOAS if the answer to either is no.

protonfish 13y ago
Of course not - it is called HYPERMEDIA as the engine of application state (not JSON.) That's why it's not called JATEOAS. The information you are asking for sounds more appropriate in an OPTIONS request.
- dragonwriter 13y ago
  > Of course not - it is called HYPERMEDIA as the engine of application state (not JSON.) If the answer to those questions is no (whether the format of the response is JSON or anything else), then you aren't using hypermedia as the engine of application state.
SilasX 13y ago
>Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Why, no, it doesn't, because it takes 3 parameters, each of which can take 10,000 possible values, and I don't want to transmit a trillion options every time someone pings the root. I mean, I considered documenting how to pass the parameters on a client's first entry but the HATEOAS crowd told me I was just re-creating RPC, and I agreed. So no HATEOAS.
- deleted 13y ago
  [deleted]