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

Designing a Pragmatic RESTful API

vinaysahni.com

Post reply on HN
Print view View original

121–130 of 139 posts

Re: Designing a Pragmatic RESTful API

#121

Post by rurounijones »

RyanMcGreal wrote: post #79
johns wrote: post #62

Earlier quoted context omitted.

Once people stop calling it the wrong thing, the discussion can be about something else. I also hate this nitpicking, but it's clearly not going away so you're better off not inviting it by using the term incorrectly.

It's why I've come to prefer the term "RESTish". It probably still isn't enough to mollify hard-core purists but indicates that, e.g. the user knows versioning ought to be in the accept header rather than the URL, but also that hardly anyone either creating or using web APIs cares.

I have always considered "RESTful" to be analagous to your "RESTish" meaning.

If I am 100% REST then I would say "I have a REST API". If, like most companies, I am not following all the REST conventions then I would say "RESTful" api.

The moaning about "RESTful has been hijacked by people who don't know REST" by the REST purists always struck me as strange when they could have made that simple distinction.

Re: Designing a Pragmatic RESTful API

#122

Post by icebraining »

bbq wrote: post #98
vyrotek wrote: post #44

Earlier quoted context omitted.

Sure, but peterwwillis was likely making the point that REST sometimes just gets in the way. REST itself is not complicated, but trying to make it work where it shouldn't can complicate what you're trying to do. Not all APIs can be modeled well with the "resource" or "document" concept. A lot of times all you really want is to ping an endpoint and get/post some data.

Maybe HTTP is simply missing the INVOKE verb for executable documents.

If you want to retrieve some data based on some parameters, you can just GET it and pass some query strings. You shouldn't need to care if the data comes from an executable file (which is usually does anyway) or someone typing it in on a terminal.

Re: Designing a Pragmatic RESTful API

#123

Post by icebraining »

jfaucett wrote: post #76
MostAwesomeDude wrote: post #14

Don't limit yourself to JSON. Your dislike of XML does not mean that JSON is always the right answer. Instead, write code that flexibly can render to any of a set of formats, and use content negotiation to determine which format the user agent wishes to consume. This lets you do things like let the read-only portion of your API be accessible via browser, and it will future-proof you.

when he says "use JSON where possible XML only where you have to", I thought it was funny, like developers out there are just dying to use this verbose behemoth instead of its terser cousin json. But anyways, I agree with everything you're saying just wondering if there actually are any devs out there who just adore some sweet XML (seriously) ?

I'm not a fan of XML, but I do like RDF, and unfortunately RDF/XML is the most common encoding format.

Re: Designing a Pragmatic RESTful API

#124

Post by jes5199 »

veesahni wrote: post #82
jfaucett wrote: post #76

Earlier quoted context omitted.

when he says "use JSON where possible XML only where you have to", I thought it was funny, like developers out there are just dying to use this verbose behemoth instead of its terser cousin json. But anyways, I agree with everything you're saying just wondering if there actually are any devs out there who just adore some sweet XML (seriously) ?

OP here. I got an email with an interesting argument on the topic. Paraphrasing: Today JSON is hip, tomorrow may be something else. By supporting XML by default and using XSLT to translate it to alternate outputs, you're able to support multiple formats without having to modify your software itself. Ofcourse, this does come with the cost of having to maintain XSLT files. To businesses that need to support multiple fo…

There's no benefit to using XSLT instead of just writing code to transform your data into another format.

Re: Designing a Pragmatic RESTful API

#125

Post by icebraining »

artsrc wrote: post #109
protonfish wrote: post #53

Earlier quoted context omitted.

Irrespective of what is good or bad design, defining an action in the URL goes against the most critical REST principles. Design it whatever way you like, but if you do this, it is not RESTful and you should not refer to it as such.

I think what you have said is correct of how, but not why. However I think what this whole discussing is missing is the properties that you derive by adhering to a REST design. I think there should be some tests of a design to see if you are actually getting the benefits of REST. For example in a REST design you can re-arrange the internal URL's in a server and the site is still usable to clients because they are fol…

The concept of putting URLs in the document is not just so that you can re-arrange them, it's so that you can use HATEOAS.

Example: think of posts here on HN. One thing a specific media format would include is a "reply" link, but on hellbanned posts that link would absent, so that state would be inaccessible to clients.

Or say you've used comments on your blog, so each post has a link to the list of comments about it. Now you switch to Disqus, and so you could change the URL to point to their comments pages instead, and a decent client would use it transparently (assuming good media types).

All of this is taken for granted and used a lot on the real RESTful space: the HTML Web.

Re: Designing a Pragmatic RESTful API

#126

Post by gizzlon »

shaydoc wrote: post #71
gizzlon wrote: post #22

Earlier quoted context omitted.

I get that you can expire it, and that helps, but it's not the same as use-once. Of course, just using a timeout is probably fine in many cases, especially if it's used with SSL. But replay attacks are still possible since there's a windows where it can be re-used.

Replay attacks are always gonna be possible unless you use a one time token or signature, thems the break's..., unless you wish to get into the something you have and something you know model. How can you do a use once token making concurrent requests without a strong authentication mechanism client side such as issuing private keys to clients....and all the PKI admin overhead. I think its safe to say, that a restful…

I'll take that as a "yes" ;)

AFAIK, neither signatures or "something you have, know" alone fixes replay attacks. Since this is a well known problem in cryptography, many solutions exists. All of which are probably overkill for this use.

Re: Designing a Pragmatic RESTful API

#127

Post by legedemon »

OP has mentioned that 'search' is not a noun and hence can't be modeled as a resource. First of all, 'search' can be used as a noun in the sense of quest/query - 'His search for the Holy Grail was fruitful.' Secondly, we happen to have a multi-model search in our application and we treat it as a resource. This has worked out very well for us and our users can easily craft search queries just like for the rest of the RESTful resources.

Re: Designing a Pragmatic RESTful API

#128

Post by shaydoc »

gizzlon wrote: post #126
shaydoc wrote: post #71

Earlier quoted context omitted.

Replay attacks are always gonna be possible unless you use a one time token or signature, thems the break's..., unless you wish to get into the something you have and something you know model. How can you do a use once token making concurrent requests without a strong authentication mechanism client side such as issuing private keys to clients....and all the PKI admin overhead. I think its safe to say, that a restful…

I'll take that as a "yes" ;) AFAIK, neither signatures or "something you have, know" alone fixes replay attacks. Since this is a well known problem in cryptography, many solutions exists. All of which are probably overkill for this use.

At least with the use of a digital signature and nonce you can guarantee that the request hasn't been tampered with!

Re: Designing a Pragmatic RESTful API

#129

Post by arethuza »

buro9 wrote: post #56

We've built a first version of an API that we have in testing at the moment, and it follows a lot of the things laid out in an ebook✝ and in the linked article. The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. I've built a couple of very pure R…

"the developer is always the customer and user"

My own criteria is that RESTful interfaces should be easy to use from the command line using curl (or any other similar tool) - not that this is the main way an interface will be used, but it helps a lot with exploration and troubleshooting.

Re: Designing a Pragmatic RESTful API

#130

Post by jlouvel »

icebraining wrote: post #57
vyrotek wrote: post #51

Earlier quoted context omitted.

Sorry. I shouldn't have over simplified that point about it being just data. I meant to emphasize that you really want to just call an operation and "just do some work". The data being just function parameters with optional data returned. I'm currently working on a few large B2B APIs and it's been difficult to implement REST. The value of these APIs come from the actual work performed and not just updating the state…

Oh no, I certainly don't think there's anything wrong or impure about not implementing REST. REST is an architectural style that, by imposing some constraints, gives you certain benefits (Fielding's paper talks about this). It's not a panacea, and it's certainly not right for every case. Just don't make an RPC API and call it RESTful ;)

I fully agree. Fielding warns in his dissertation about design by buzzwords himself.

Almost all web APIs out there aren't REST APIs because they don't respect the "driven by hypermedia" constraint which makes sense because this constraint was put in place for human users driving applications through web browsers, not for machines.

I've started to formalize a new "Web API" architecture style that takes the best of REST but leaves the requirements and constraints that don't make sense. See this blog post: http://blog.restlet.com/2013/05/02/how-much-rest-should-your...

Post reply on HN