4 ms·

I must disagree. REST is defined by four interface constraints: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5 http://www.ics.

I must disagree. REST is defined by four interface constraints: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... and identification of resources is the first principle. This functionality is implemented by URLs in HTTP and is therefore critical. HATEOAS (the 4th principle) also seems to be gravely misunderstood. It only means that the API should have a version that is fully useable in a web browser.

sjtgraham 12y ago
Incorrect. Resources are identified by URIs, but they are opaque, n.b. The Opacity Axiom "The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information." http://www.w3.org/DesignIssues/Axioms.html#opaque http://www.w3.org/DesignIssues/Axioms.html#opaque
wahnfrieden 12y ago
What the URLs look like is not a concern of REST though. Can you cite your latter point, since that's contrary to how I've seen HATEOAS explained? Many libraries do expose a browser-navigable form of the API, but I can't see how that's how it's originally defined nor it being a requirement.
- protonfish 12y ago
  Are you saying that it's just as good to have a URL be /fj3849-2qfjimpa as /customer? I agree that it is not strictly a REST principle, but in an API clarity matters. If we are talking about good practices, would your rather work with an REST API with readable, concise URLs or not? Maybe I am missing the point but the URL is one of the major building blocks of REST and choosing quality ones is a large part of API design. I stated that HATEOAS is widely misunderstood so it isn't surprising that there are conflicting descriptions out there. No matter what your interpretation, this principle is about hypermedia and application state and says nothing about what a URL should or should not be.
  - dragonwriter 12y ago
    > Are you saying that it's just as good to have a URL be /fj3849-2qfjimpa as /customer? I agree that it is not strictly a REST principle, but in an API clarity matters. No, it is strictly a REST principle that the meaning of URLs other than the entry point is defined completely by the context in which they are used in resource representations and the definition of those resource representation (i.e., media types). An implementation of a REST API may happen to present URLs with a consistent relationship of location structure to semantic meaning in the API, but that's entirely outside the scope of the REST API per se. > If we are talking about good practices, would your rather work with an REST API with readable, concise URLs or not? If you are using HATEOAS, URL format, readable or not, isn't a feature of the API at all (its a feature of a particular implementation of the API, but its one that clients don't need to be aware of.) > Maybe I am missing the point but the URL is one of the major building blocks of REST and choosing quality ones is a large part of API design. You are missing the point. URLs as opaque identifiers is one of the major building blocks of rest, and if you are worried about choosing one as part of "API design", you aren't building a REST API. The resource representation (media type) should tell you what the URLs used in it are for, not the URLs themselves. > I stated that HATEOAS is widely misunderstood so it isn't surprising that there are conflicting descriptions out there. No matter what your interpretation, this principle is about hypermedia and application state and says nothing about what a URL should or should not be. If you need to communicate the URL structure and identify relative URLs for various endpoints to describe an API, it is not a REST API following HATEOAS; "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API)." [1] HATEOAS clearly is misunderstood, as you've just demonstrated. [1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
arethuza 12y ago
I've always interpreted "hypertext" in this context to mean "a document containing hyperlinks" in a rather general sense - nothing about it being restricted to HTML.
dragonwriter 12y ago
> HATEOAS (the 4th principle) also seems to be gravely misunderstood. It only means that the API should have a version that is fully useable in a web browser. No, it doesn't. In fact, a REST API can fully meet the requirements Fielding lays out without having any implementation that uses any communication protocol used by any web browser. REST is an architectural pattern that is independent of communication protocols.
- dustingetz 12y ago
  Hi dragonwriter, is there a way that I can contact you with a few questions about REST that aren't appropriate for here? Twitter, IRC, email?
protonfish 12y ago
My statement that HATEOAS is misunderstood is corroborated over and over by the replies to my comment. HATEOAS being misunderstood is so weird because it is an acronym of its own definition so I have no idea where all these other definitions are coming from. Let's examine it closer. HATEOAS stands for: Hypermedia as the engine of application state Hypermedia means HTML, period. Putting a list of URLs in a text or JSON response does not magically make it hypermedia. Engine of application state means that all representations of the resources must be possible. Combine those two and it means that all functionality must be accessible to and from the text/html content type. It must be able to handle all supported HTTP verbs and no fancy request headers that are not supported by HTML forms or hyperlinks.
- paulddraper 12y ago
  "Hypermedia means HTML, period." Um, no. XHTML and SVG are hypermedia. JSON isn't hypermedia, but you can define hypermedia formats that use JSON (just as SVG uses XML).
  - protonfish 12y ago
    True, but with so much confusion over a blatantly clear definition I figured I needed to keep it simple.
- dragonwriter 12y ago
  > Hypermedia means HTML, period. Wrong. Any resource representation that can contain links to other resources with semantic identification of the relationship they have with the current resource is hypermedia. HTML is particularly popular, but far from the only hypermedia format. > Putting a list of URLs in a text or JSON response does not magically make it hypermedia. No, not magically, but if you have URLs with identification of their relationship to the current document in JSON, it is hypermedia. Hypermedia is older than HTML, and extends well beyond it. > Engine of application state means that all representations of the resources must be possible. No, it doesn't. HATEOAS does not mean that all resources must have hypermedia representations, it means that all available actions on the application state (whether read actions or write actions) must be identified to the client through hypermedia. (E.g., through links communicated in hypermedia resource representations wherein the semantics of the representation and the media-type of the resource in which it appears and which applies to the linked resource define the available actions.) A resource representation to which access is provided via a hypermedia link but which does not define additional linked resources need not be in a hypermedia format (that is, some resources may be purely defined by things like straight -- not hyper- -- text resources, or images, or whatever.) > Combine those two and it means that all functionality must be accessible to and from the text/html content type. It doesn't mean that at all. What HATEOAS means is laid out most clearly by Roy Fielding in a blog post responding to the way in which his definition of REST had been misunderstood on this point: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... REST isn't about HTML or the Web, though the Web and HTML are the inspiration for the definition of the REST architectural style. REST (and HATEOAS more specifically) requires neither HTML, nor any of the other specific technologies (HTTP, etc.) that define "the Web".
jayvanguard 12y ago
His dissertation is quite out of date with respect to current practical experience. Some of the ideas turned out to be great, others largely irrelevant. It was very useful at the time but don't forget it was realistically based on less than a handful of years of real industry experience. And most of that was in reaction to SOAP/SOA wars. Before and during the time it was written there were existing HTTP based web services that were successful and they didn't follow all the principles outlined in the dissertation. Fast-forward 15 years and the vast majority of successful HTTP based web services still don't follow all the principles. Some turned out to be more useful than others.

sjtgraham 12y ago

Incorrect. Resources are identified by URIs, but they are opaque, n.b. The Opacity Axiom "The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information." http://www.w3.org/DesignIssues/Axioms.html#opaque http://www.w3.org/DesignIssues/Axioms.html#opaque

wahnfrieden 12y ago

What the URLs look like is not a concern of REST though. Can you cite your latter point, since that's contrary to how I've seen HATEOAS explained? Many libraries do expose a browser-navigable form of the API, but I can't see how that's how it's originally defined nor it being a requirement.

protonfish 12y ago
Are you saying that it's just as good to have a URL be /fj3849-2qfjimpa as /customer? I agree that it is not strictly a REST principle, but in an API clarity matters. If we are talking about good practices, would your rather work with an REST API with readable, concise URLs or not? Maybe I am missing the point but the URL is one of the major building blocks of REST and choosing quality ones is a large part of API design. I stated that HATEOAS is widely misunderstood so it isn't surprising that there are conflicting descriptions out there. No matter what your interpretation, this principle is about hypermedia and application state and says nothing about what a URL should or should not be.
- dragonwriter 12y ago
  > Are you saying that it's just as good to have a URL be /fj3849-2qfjimpa as /customer? I agree that it is not strictly a REST principle, but in an API clarity matters. No, it is strictly a REST principle that the meaning of URLs other than the entry point is defined completely by the context in which they are used in resource representations and the definition of those resource representation (i.e., media types). An implementation of a REST API may happen to present URLs with a consistent relationship of location structure to semantic meaning in the API, but that's entirely outside the scope of the REST API per se. > If we are talking about good practices, would your rather work with an REST API with readable, concise URLs or not? If you are using HATEOAS, URL format, readable or not, isn't a feature of the API at all (its a feature of a particular implementation of the API, but its one that clients don't need to be aware of.) > Maybe I am missing the point but the URL is one of the major building blocks of REST and choosing quality ones is a large part of API design. You are missing the point. URLs as opaque identifiers is one of the major building blocks of rest, and if you are worried about choosing one as part of "API design", you aren't building a REST API. The resource representation (media type) should tell you what the URLs used in it are for, not the URLs themselves. > I stated that HATEOAS is widely misunderstood so it isn't surprising that there are conflicting descriptions out there. No matter what your interpretation, this principle is about hypermedia and application state and says nothing about what a URL should or should not be. If you need to communicate the URL structure and identify relative URLs for various endpoints to describe an API, it is not a REST API following HATEOAS; "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API)." [1] HATEOAS clearly is misunderstood, as you've just demonstrated. [1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

arethuza 12y ago

I've always interpreted "hypertext" in this context to mean "a document containing hyperlinks" in a rather general sense - nothing about it being restricted to HTML.

dragonwriter 12y ago

> HATEOAS (the 4th principle) also seems to be gravely misunderstood. It only means that the API should have a version that is fully useable in a web browser. No, it doesn't. In fact, a REST API can fully meet the requirements Fielding lays out without having any implementation that uses any communication protocol used by any web browser. REST is an architectural pattern that is independent of communication protocols.

dustingetz 12y ago
Hi dragonwriter, is there a way that I can contact you with a few questions about REST that aren't appropriate for here? Twitter, IRC, email?

protonfish 12y ago

My statement that HATEOAS is misunderstood is corroborated over and over by the replies to my comment. HATEOAS being misunderstood is so weird because it is an acronym of its own definition so I have no idea where all these other definitions are coming from. Let's examine it closer. HATEOAS stands for: Hypermedia as the engine of application state Hypermedia means HTML, period. Putting a list of URLs in a text or JSON response does not magically make it hypermedia. Engine of application state means that all representations of the resources must be possible. Combine those two and it means that all functionality must be accessible to and from the text/html content type. It must be able to handle all supported HTTP verbs and no fancy request headers that are not supported by HTML forms or hyperlinks.

paulddraper 12y ago
"Hypermedia means HTML, period." Um, no. XHTML and SVG are hypermedia. JSON isn't hypermedia, but you can define hypermedia formats that use JSON (just as SVG uses XML).
- protonfish 12y ago
  True, but with so much confusion over a blatantly clear definition I figured I needed to keep it simple.
dragonwriter 12y ago
> Hypermedia means HTML, period. Wrong. Any resource representation that can contain links to other resources with semantic identification of the relationship they have with the current resource is hypermedia. HTML is particularly popular, but far from the only hypermedia format. > Putting a list of URLs in a text or JSON response does not magically make it hypermedia. No, not magically, but if you have URLs with identification of their relationship to the current document in JSON, it is hypermedia. Hypermedia is older than HTML, and extends well beyond it. > Engine of application state means that all representations of the resources must be possible. No, it doesn't. HATEOAS does not mean that all resources must have hypermedia representations, it means that all available actions on the application state (whether read actions or write actions) must be identified to the client through hypermedia. (E.g., through links communicated in hypermedia resource representations wherein the semantics of the representation and the media-type of the resource in which it appears and which applies to the linked resource define the available actions.) A resource representation to which access is provided via a hypermedia link but which does not define additional linked resources need not be in a hypermedia format (that is, some resources may be purely defined by things like straight -- not hyper- -- text resources, or images, or whatever.) > Combine those two and it means that all functionality must be accessible to and from the text/html content type. It doesn't mean that at all. What HATEOAS means is laid out most clearly by Roy Fielding in a blog post responding to the way in which his definition of REST had been misunderstood on this point: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... REST isn't about HTML or the Web, though the Web and HTML are the inspiration for the definition of the REST architectural style. REST (and HATEOAS more specifically) requires neither HTML, nor any of the other specific technologies (HTTP, etc.) that define "the Web".

jayvanguard 12y ago

His dissertation is quite out of date with respect to current practical experience. Some of the ideas turned out to be great, others largely irrelevant. It was very useful at the time but don't forget it was realistically based on less than a handful of years of real industry experience. And most of that was in reaction to SOAP/SOA wars. Before and during the time it was written there were existing HTTP based web services that were successful and they didn't follow all the principles outlined in the dissertation. Fast-forward 15 years and the vast majority of successful HTTP based web services still don't follow all the principles. Some turned out to be more useful than others.