RESTful API Server - Doing it right • Hacker News Board

Re: RESTful API Server - Doing it right

#11

Post by RyanMcGreal » Fri, Mar 02, 2012, 1:07 PM UTC

tomstuart wrote: post #4

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 an…

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.

Re: RESTful API Server - Doing it right

#12

Post by [deleted] » Fri, Mar 02, 2012, 1:07 PM UTC

tomstuart wrote: post #4

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 an…

[deleted]

Re: RESTful API Server - Doing it right

#13

Post by MugunthKumar » Fri, Mar 02, 2012, 1:13 PM UTC

nikcub wrote: post #10

icebraining wrote: post #3

Sorry, but it lacks the most misunderstood parts of REST: - Hypermedia as the Engine of Application State (HATEOAS) - Returning concrete mediatypes (standard is great, custom is OK) instead of generic 'application/json' or 'application/xml' It also contains some misunderstandings: - Sending a sha1 of the password to the server is bad, for two reasons: - - First, and more importantly, if you send the hash of the passw…

not to mention version numbers (a part of content negotiation) in user agents this isn't REST and only serves to confuse things further

I agree. Updating my post on this. Thanks.

Re: RESTful API Server - Doing it right

#14

Post by MugunthKumar » Fri, Mar 02, 2012, 1:15 PM UTC

arethuza wrote: post #9

MugunthKumar wrote: post #8

I haven't written anything about HATEOAS, caching and Internationalization intentionally as I'm reserving it for another post.

That's a bit like writing an article on how to design boats and reserving mentioning water.

I did mention that it's incomplete. It's impossible to write the complete thing in one post.

Re: RESTful API Server - Doing it right

#15

Post by icebraining » Fri, Mar 02, 2012, 1:23 PM UTC

RyanMcGreal wrote: post #11

tomstuart wrote: post #4

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 an…

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 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.

Re: RESTful API Server - Doing it right

#16

Post by RyanMcGreal » Fri, Mar 02, 2012, 1:43 PM UTC

icebraining wrote: post #15

RyanMcGreal wrote: post #11

Earlier quoted context omitted.

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 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.

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.

Re: RESTful API Server - Doing it right

#17

Post by brunoqc » Fri, Mar 02, 2012, 2:07 PM UTC

About RESTful API, if you have many applications working together, do you build an API and use it in every application or is the API only for applications you don't control and you use the same code that you use for the API in every application you control?

Re: RESTful API Server - Doing it right

#18

Post by arethuza » Fri, Mar 02, 2012, 2:10 PM UTC

RyanMcGreal wrote: post #16

icebraining wrote: post #15

Earlier quoted context omitted.

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.

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 tryi…

Maybe I'm missing something, but why the resistance to returning a "meaningful" content type in a response? It's just a name for the structure you have outlined there.

Re: RESTful API Server - Doing it right

#19

Post by valugi » Fri, Mar 02, 2012, 2:11 PM UTC

what's with the PHP hate?

Re: RESTful API Server - Doing it right

#20

Post by icebraining » Fri, Mar 02, 2012, 2:18 PM UTC

RyanMcGreal wrote: post #16

icebraining wrote: post #15

Earlier quoted context omitted.

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.

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 tryi…

What trouble? Are you not documenting what you return anyway? What's the cost of just changing the mediatype to some different string?

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?

Personally, I think that mindset will hold us back. People still think of RESTful services as closed silos instead of open, truly uniform interfaces, and that will prevent us from growing, in my opinion.

Your view is of a developer painstakingly coding against each API (s)he wants to use, manually prodding and poking it and writing a custom library that doesn't work with any other service.

My view is of generic, easily adaptable clients, using machine-readable specification of formats¹ and providing graphical UIs where even non-programmers can input the single endpoints of various services and easily combine the data and functionality to create applications that cater to their specific needs.

I see a service like IFTTT[1], but more flexible and where the services are not hardcoded but imported dynamically by the user and then strung together to fit their needs.

Using mediatypes, even if custom, is a step towards that integration and standardization that makes this possible.

¹ RDF seems like the best bet to me - possibly encoded as JSON

[1]: http://ifttt.com/