6 ms·

I realise it's only part 1, but this post doesn't even mention hypermedia. Its advice on documentation says that you should explain how clients construct URIs.

I realise it's only part 1, but this post doesn't even mention hypermedia. Its advice on documentation says that you should explain how clients construct URIs. Groan. I don't fully understand what it is about HATEOAS that people find difficult or unconvincing. They must use web sites every day. When you want to buy a book at Amazon, do you read their documentation and then construct a URL? No, you go to amazon.com and click on shit.

arethuza 15y ago
I must admit that the author's description of REST sounds awfully like what I thought REST was before I sat down and tried to design a RESTful API. There was a very distinct moment when I "got" the concept of only requiring a single URL and then navigating the resulting documents - as you say exactly like a web browser (which is, of course, the whole point). It's clearly non-obvious to work with an API primarily as a set of documents rather than as a set of "methods" to be called - I have no idea why it's non-obvious at the start as it is exactly how the Web works and it's pretty obvious and elegant in retrospect.
- deleted 15y ago
  [deleted]
- uxp 15y ago
  I feel the same way. My first API on my current project was a horrible mess, and did I only realize why it sucked and what I needed to change when I decided to play with Backbone.js over a weekend using my API as a data source. The only way, I think, one can build a RESTful API is to do it from the client's perspective, much like BDD builds software using a list of actions the user wants to make. If you're not using your own API, then it's probably broken.
  - arethuza 15y ago
    I found that manually using my API from the command line using cURL helped a lot (with a bit of cutting and pasting to extract the URLs I want).
RyanMcGreal 15y ago
HATEOAS is absolutely not a simple matter of being able to 'click on shit' in a web service. As a browser user, I can generally look at a web page and figure out what's a clickable link. The HATEOAS constraint is rather trickier than that: it requires that a client understand what is a "clickable" link in an HTTP response based on nothing other than the content type and the response body. For the past couple of years I've been building RESTish web services using JSON. They use HTTP methods and status codes appropriately, each resource has a URL, my response objects include URLs to subsidiary resources, and so on. However, the services I've built are not RESTful because JSON is not a hypermedia content type. To be truly RESTful, I would need to adopt and/or define a hypermedia content-type using JSON and make sure my response objects conform to that content-type.
- icebraining 15y ago
  I don't get it: what's so difficult about defining a format - encoded as JSON - in which certain strings are defined as being URLs you can navigate to? You just say "This is the format application/vnd.myservice.userprofile+json". In it there's an object, which contains the key "avatar_url", which has the URL of the user's avatar image. Frankly, I don't see what's tricky about this.
  - RyanMcGreal 15y ago
    It's yet another implementation detail that drags the reality of RESTful web service development farther away from the principle that it's easy because it's based on HTTP and we already know HTTP. I'm not writing this to dump on REST. I still think it's the right approach to build a web service over HTTP, but I'm also conscious of the diminishing returns on each incremental step toward pure RESTfulness. I'm just trying to make a web service, and suddenly I'm defining new content-types? For a client, is it worth the trouble to learn a new content-type to determine what's a hyperlink in my JSON response, when they can just look at the response and see something like the following? GET /articles HTTP/1.1 { "articles": [ { "url": "/articles/1", "title": "This is my first article", "pubDate": "2012-01-05T08:39:47.625000 }, { "url": "/articles/2", "title": "This is my second article", "pubDate": "2012-01-13T11:07:35.219000 } ] } After a while it starts to feel like the HTML v. XHTML debate.
deleted 15y ago
[deleted]

arethuza 15y ago

I must admit that the author's description of REST sounds awfully like what I thought REST was before I sat down and tried to design a RESTful API. There was a very distinct moment when I "got" the concept of only requiring a single URL and then navigating the resulting documents - as you say exactly like a web browser (which is, of course, the whole point). It's clearly non-obvious to work with an API primarily as a set of documents rather than as a set of "methods" to be called - I have no idea why it's non-obvious at the start as it is exactly how the Web works and it's pretty obvious and elegant in retrospect.

deleted 15y ago
[deleted]
uxp 15y ago
I feel the same way. My first API on my current project was a horrible mess, and did I only realize why it sucked and what I needed to change when I decided to play with Backbone.js over a weekend using my API as a data source. The only way, I think, one can build a RESTful API is to do it from the client's perspective, much like BDD builds software using a list of actions the user wants to make. If you're not using your own API, then it's probably broken.
- arethuza 15y ago
  I found that manually using my API from the command line using cURL helped a lot (with a bit of cutting and pasting to extract the URLs I want).

RyanMcGreal 15y ago

HATEOAS is absolutely not a simple matter of being able to 'click on shit' in a web service. As a browser user, I can generally look at a web page and figure out what's a clickable link. The HATEOAS constraint is rather trickier than that: it requires that a client understand what is a "clickable" link in an HTTP response based on nothing other than the content type and the response body. For the past couple of years I've been building RESTish web services using JSON. They use HTTP methods and status codes appropriately, each resource has a URL, my response objects include URLs to subsidiary resources, and so on. However, the services I've built are not RESTful because JSON is not a hypermedia content type. To be truly RESTful, I would need to adopt and/or define a hypermedia content-type using JSON and make sure my response objects conform to that content-type.

icebraining 15y ago
I don't get it: what's so difficult about defining a format - encoded as JSON - in which certain strings are defined as being URLs you can navigate to? You just say "This is the format application/vnd.myservice.userprofile+json". In it there's an object, which contains the key "avatar_url", which has the URL of the user's avatar image. Frankly, I don't see what's tricky about this.
- RyanMcGreal 15y ago
  It's yet another implementation detail that drags the reality of RESTful web service development farther away from the principle that it's easy because it's based on HTTP and we already know HTTP. I'm not writing this to dump on REST. I still think it's the right approach to build a web service over HTTP, but I'm also conscious of the diminishing returns on each incremental step toward pure RESTfulness. I'm just trying to make a web service, and suddenly I'm defining new content-types? For a client, is it worth the trouble to learn a new content-type to determine what's a hyperlink in my JSON response, when they can just look at the response and see something like the following? GET /articles HTTP/1.1 { "articles": [ { "url": "/articles/1", "title": "This is my first article", "pubDate": "2012-01-05T08:39:47.625000 }, { "url": "/articles/2", "title": "This is my second article", "pubDate": "2012-01-13T11:07:35.219000 } ] } After a while it starts to feel like the HTML v. XHTML debate.

deleted 15y ago

[deleted]