Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why and How You Should Write REST-Centric Applications

w2lessons.com

Post reply on HN
Print view View original

21–30 of 33 posts

Re: Why and How You Should Write REST-Centric Applications

#21

Post by mpakes »

sradnidge wrote: post #3

Nice post. The single biggest criticism I usually level at REST implementations is the lack of HATEOAS - the discoverability aspect of REST is about more than just an easily understood URI. As the author of this post states in his 2nd bullet point (emphasis mine): "It’s expressive, REST paths and CRUD requests are easy to understand _and hypermedia makes it easy to navigate_" It's that second part that so many implem…

It's no accident that many public web APIs don't implement HATEOAS. Conceptually, HATEOAS is fantastic. Practically, it often stumbles.

As an example, 90+% of the web APIs I've designed and worked with are heavily used by mobile clients, which often suffer low bandwidth and high latency. Using proper HATEOAS URIs bloats payloads. Similarly, high latency for requests means that traversing hypermedia links across the API space is untenable.

In the real world, we design a structured API with well-known endpoints, and clients directly retrieve the resources they need. If the API needs to diverge from the specification substantially, then it gets versioned. The result is small, simple JSON payloads and nice, responsive clients.

If I'm missing something obvious here, I'd love to be educated.

Re: Why and How You Should Write REST-Centric Applications

#22

Post by leftnode »

extension wrote: post #18
leftnode wrote: post #17

Earlier quoted context omitted.

Wait, why not? The JSON could return in a standard format that the client knows where to look for links to other documents.

Sure, you can design a standard format on top of JSON, but that is rarely done. The whole appeal of it is for passing around ad-hoc data structures. There are many hypermedia formats built on XML, but when it's just used as a data container for an API, it's not hypermedia.

Gotcha, that makes sense. Thanks.

Re: Why and How You Should Write REST-Centric Applications

#23

Post by ataggart »

Sym3tri wrote: post #20

Authentication and need for at least a pseudo "session state" always seems like the trickiest part of building a 100% RESTful app. Anyone have details/examples on ways to address these?

One approach I've seen regarding auth is to use a faux-resource:

Login:

    PUT https://example.com/credentials
    {"username":"foo", "password":"bar"}
Check if user is logged in:

    HEAD http://example.com/credentials
    Cookie: ...
Get current user:

    GET http://example.com/credentials
    Cookie: ...
Logout:

    DELETE http://example.com/credentials
    Cookie: ...
From the point of view of the one client, it's no less "real" than any other resource.

Re: Why and How You Should Write REST-Centric Applications

#24

Post by ataggart »

notJim wrote: post #19
methodin wrote: post #4

RESTful APIs can be a pain when you have to mashup different APIs, though. The amount of calls you end up having to do can be quite a lot. From a backend standpoint it's not that bad if you cache, but from a consumer standpoint I have to get a /users/active list, iterate over them, then call a /friends/[id] call for every user. If you add a third list you can easily see how annoying it might be. It's great that your…

This is an issue I'd like see more people talk about in REST API design. There's quite a balance to be struck between the number of calls to be made and the size of the data that needs to be download. I designed a REST API that's primarily (well, currently only) used for mobile applications, and it was often hard to decide whether to “denormalize“ the API (fewer API calls required, but more data per call) or provide…

One need not exclusively describe every sublist as a separate resource. Sorting and filtering can correctly be implemented as query params on the full list resource. Perhaps the shunning of query params (rightfully so when used as verbs) has gone too far.

Re: Why and How You Should Write REST-Centric Applications

#25

Post by sradnidge »

mpakes wrote: post #21
sradnidge wrote: post #3

Nice post. The single biggest criticism I usually level at REST implementations is the lack of HATEOAS - the discoverability aspect of REST is about more than just an easily understood URI. As the author of this post states in his 2nd bullet point (emphasis mine): "It’s expressive, REST paths and CRUD requests are easy to understand _and hypermedia makes it easy to navigate_" It's that second part that so many implem…

It's no accident that many public web APIs don't implement HATEOAS. Conceptually, HATEOAS is fantastic. Practically, it often stumbles. As an example, 90+% of the web APIs I've designed and worked with are heavily used by mobile clients, which often suffer low bandwidth and high latency. Using proper HATEOAS URIs bloats payloads. Similarly, high latency for requests means that traversing hypermedia links across the A…

Sure, but I'm sure Roy Fielding would argue you can't have REST without HATEOAS. So on some level yes, it is great in theory, but on another level I would also argue that's where the 'ful' comes in ala 'RESTful'. I guess you could look at it in a 'spirit of the law vs letter of the law' kind of way - REST without HATEOAS is certainly in the spirit, but perhaps so is XML-RPC with HATEOAS. Neither are the letter though.

The website example below is a good one, but as I'm and infrastructure oriented kind of guy I'll give another one which is the Sun Cloud API, under the now defunct project Kenai http://kenai.com/projects/suncloudapis/pages/Home. For example, doing a GET on a VM resource will return a payload that contains a URI for a power operation on the VM. What that power operation is obviously depends on what the power state of the VM at the time of the GET. The AWS API's provide a SOAPy interface, but they return information about objects that much more adheres to HATEOAS than the Rackspace API for example, which goes to _great_ lengths to espouse it's RESTy virtues (even consisently, and incorrectly, lowering the 'E' in the API docs lol).

So yeh, of course it all comes down to the infinite scales of grey, I wasn't trying to imply that I know any better than anyone or that REST-without-HATEOAS is wrong or suboptimal or whatever (and I know you're not interpreting it that way either), just that I have sometimes wondered how many REST implementors actually took the time to understand what Fielding was/is on about. And I certainly don't believe you or the author of the post fall into that category!

Re: Why and How You Should Write REST-Centric Applications

#26

Post by methodin »

notJim wrote: post #19
methodin wrote: post #4

RESTful APIs can be a pain when you have to mashup different APIs, though. The amount of calls you end up having to do can be quite a lot. From a backend standpoint it's not that bad if you cache, but from a consumer standpoint I have to get a /users/active list, iterate over them, then call a /friends/[id] call for every user. If you add a third list you can easily see how annoying it might be. It's great that your…

This is an issue I'd like see more people talk about in REST API design. There's quite a balance to be struck between the number of calls to be made and the size of the data that needs to be download. I designed a REST API that's primarily (well, currently only) used for mobile applications, and it was often hard to decide whether to “denormalize“ the API (fewer API calls required, but more data per call) or provide…

I know what you mean. I've often shied away from using REST simply because I like to setup the APIs as classes and use the classes directly in my internal code usage. REST breaks that for me, not only because the paradigm is different, but if it was truly REST I'd be making CURL calls to myself to get the data which single-handedly bloats my code by an order of magnitude... It definitely deserves some discussion to find out if there is a way around this problem as blindly going REST can cause some very difficult problems down the road.

Re: Why and How You Should Write REST-Centric Applications

#27

Post by smackay »

ataggart wrote: post #24
notJim wrote: post #19

Earlier quoted context omitted.

This is an issue I'd like see more people talk about in REST API design. There's quite a balance to be struck between the number of calls to be made and the size of the data that needs to be download. I designed a REST API that's primarily (well, currently only) used for mobile applications, and it was often hard to decide whether to “denormalize“ the API (fewer API calls required, but more data per call) or provide…

One need not exclusively describe every sublist as a separate resource. Sorting and filtering can correctly be implemented as query params on the full list resource. Perhaps the shunning of query params (rightfully so when used as verbs) has gone too far.

Hear, hear. REST APIs are particularly difficult to implement when you have multiple optional value to query/describe a particular set of resources. The RESTful way encourages an explosion of URLs to try and support the different combinations. Adding new ways to list resources at a later date is also next to impossible. Query parameters simplify the process and the API significantly and still make it easy to describe and use. For me the best approach is to mix the two: make often used, pre-defined queries RESTful then support all the specialised combinations through query parameters.

Re: Why and How You Should Write REST-Centric Applications

#28

Post by justincormack »

notJim wrote: post #15
sradnidge wrote: post #3

Nice post. The single biggest criticism I usually level at REST implementations is the lack of HATEOAS - the discoverability aspect of REST is about more than just an easily understood URI. As the author of this post states in his 2nd bullet point (emphasis mine): "It’s expressive, REST paths and CRUD requests are easy to understand _and hypermedia makes it easy to navigate_" It's that second part that so many implem…

I wrote an api that has HATEOAS, but none of the devs really use it. They seem to prefer hardcoding strings.

The hardcore randomly change all the urls in testing to make sure nothing is hardcoded. A hateos api should still work.

Re: Why and How You Should Write REST-Centric Applications

#29

Post by notJim »

justincormack wrote: post #28
notJim wrote: post #15

Earlier quoted context omitted.

I wrote an api that has HATEOAS, but none of the devs really use it. They seem to prefer hardcoding strings.

The hardcore randomly change all the urls in testing to make sure nothing is hardcoded. A hateos api should still work.

Haha, I thought about doing that, but it would just serve to piss a lot of people off.

I think it would be kind of cool to have a little project/developer toy that would be an API where only a single endpoint was provided (think http://mysteryapi.com), and the rest of it had to be discovered. It could be like the labyrinth from House of Leaves, but in REST API format.

Re: Why and How You Should Write REST-Centric Applications

#30

Post by extension »

sradnidge wrote: post #25
mpakes wrote: post #21

Earlier quoted context omitted.

It's no accident that many public web APIs don't implement HATEOAS. Conceptually, HATEOAS is fantastic. Practically, it often stumbles. As an example, 90+% of the web APIs I've designed and worked with are heavily used by mobile clients, which often suffer low bandwidth and high latency. Using proper HATEOAS URIs bloats payloads. Similarly, high latency for requests means that traversing hypermedia links across the A…

Sure, but I'm sure Roy Fielding would argue you can't have REST without HATEOAS. So on some level yes, it is great in theory, but on another level I would also argue that's where the 'ful' comes in ala 'RESTful'. I guess you could look at it in a 'spirit of the law vs letter of the law' kind of way - REST without HATEOAS is certainly in the spirit, but perhaps so is XML-RPC with HATEOAS. Neither are the letter though…

The important quality that HATEOAS gives you is the freedom to evolve the application on the server without changing the client. It's the reason that the web can be used for things that TBL didn't anticipate when he invented it. If an API can't adopt new functionality without breaking clients then there is no sense in calling it RESTful.

As other commenters, and Fielding himself, have pointed out, REST is inefficient in terms of both computer and human resources. It's an architecture optimized for wide scale and long term use. That's why most APIs don't turn out very RESTful.

Post reply on HN