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

91–100 of 139 posts

Re: Designing a Pragmatic RESTful API

#91

Post by dragonwriter »

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…

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

By separating out the rendering-to-an-output format from the basic logic of the application, you get similar benefits without creating a dependency on XML handling libraries and requiring another implementation language (XSLT) for the rendering component.

Re: Designing a Pragmatic RESTful API

#92

Post by sopooneo »

just2n wrote: post #89
h2s wrote: post #77

Earlier quoted context omitted.

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. Thank you, this articulates my disagreement with the idea of hashing all URLs so that client developers are forced to follow links returned by the API instead of generating their own URLs http://…

There's nothing really wrong with RPC-like APIs. They're often much simpler to use in modern web development, for developers with access to documentation. Hyperlinking has a few benefits, the biggest being discoverability without the need for browsing some documentation that explains how to build URLs, but it's not always the best possible solution for every application -- and it typically leads to chatty application…

This speaks to something that has baffled me for a long time. If we have to bend/break the rules of REST to make things usable in the real world (and I believe we do), why have REST as an ideal in the first place?

Why work halfway towards A, when we could define a more realistic B and implement it fully? We spend too much time justifying which parts of the holy book to ignore.

Re: Designing a Pragmatic RESTful API

#93

Post by vyrotek »

dragonwriter wrote: post #90
ebiester wrote: post #86

Earlier quoted context omitted.

I can think of an example: Send a message to the server to process all approved cases, which has no connection to an individual resource. The client has no fundamental knowledge of all server-side resources that may or may not be affected, and may not even be allowed that information. It's an action, but it's not really a post. You're not creating a new resource. You're not patching anything, you're not really gettin…

> Send a message to the server to process all approved cases, which has no connection to an individual resource. "Individual resources" are defined by the needs of the API. If you need an endpoint that can be given a command to process all approved cases, then that is an "individual resource". The particular kind of resource I'd normally model it as is one which is or has a collection resource in which individual com…

"REST doesn't expect a "document-based API". It expects a resource based API. Commands, collections of commands, and endpoints which have collections of commands as well as other subordinate resources are all, themselves, valid resources, whether or not they are sensibly described as "documents"."

Ah, well said. It's so hard to find good examples of this though. Most REST tutorials focus on simple nouns that happen to map nicely to tables. But you're suggesting that "resources" could be far more abstract. But, if I were to treat Commands as resource and perhaps make it my only resource, isn't that essentially RPC?

Re: Designing a Pragmatic RESTful API

#94

Post by Torn »

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 apigee doc is a great resource. The PDF is also indexed directly via google if you don't want to sign up: info.apigee.com/Portals/62317/docs/web%20api.pdf

Re: Designing a Pragmatic RESTful API

#95

Post by CodeFoo »

Great article, I've read many like it, BUT what I can't find is information pertinent to how one should host their API. I submitted an "Ask HN" (https://news.ycombinator.com/item?id=5820761) earlier, but could some folks please advise me on the hosting side of "Designing a Pragmatic RESTful API"?

Re: Designing a Pragmatic RESTful API

#96

Post by dragonwriter »

vyrotek wrote: post #93
dragonwriter wrote: post #90

Earlier quoted context omitted.

> Send a message to the server to process all approved cases, which has no connection to an individual resource. "Individual resources" are defined by the needs of the API. If you need an endpoint that can be given a command to process all approved cases, then that is an "individual resource". The particular kind of resource I'd normally model it as is one which is or has a collection resource in which individual com…

"REST doesn't expect a "document-based API". It expects a resource based API. Commands, collections of commands, and endpoints which have collections of commands as well as other subordinate resources are all, themselves, valid resources, whether or not they are sensibly described as "documents"." Ah, well said. It's so hard to find good examples of this though. Most REST tutorials focus on simple nouns that happen t…

> But, if I were to treat Commands as resource and perhaps make it my only resource, isn't that essentially RPC?

If you have a root URL for the API, and all the endpoints are located via links from the document at the root URL, and submitting commands gives back a results resource that either is or provides a URL for the output, and all the different resources have media types that define what is needed to understand/process them without requiring out-of-band information beyond that describing the media types and the root URL of the API, then it can still be REST.

I think its probably fairly common that there are situations where the "active" side of a REST API will largely look that way, even if there is a read-only component that looks like of the collection-resources-as-tables, individual-resources-as-table-rows business data view.

That being said, its probably not really good REST if things being modelled as abstract commands with side effect of changes on multiple entities really could be modeled as changes to some particular business entity that also had side effects on other business entities. But whether that applies to the commands you are using will depend on your use case.

Re: Designing a Pragmatic RESTful API

#97

Post by Torn »

kailuowang wrote: post #43
protonfish wrote: post #40

Earlier quoted context omitted.

Um, how about POST /blog/id/ and in the request body revert=version# Seriously REST isn't a mystery. I think the problem is few understand what it is. Here is my 30-second version: 1. Identification of resources and manipulation through representations. This means a network resource should have a URL that is the same no matter what you are doing to it - getting changing, removing, modifying or any custom manipulation…

I am not sure how RESTful that looks to me. I would like to route to the action from the url rather than having to read what's in the body. In your solution, I would need that body parser to differentiate this revert action from an update action.

RESTful interfaces use HTTP verbs (actions), and the urls contain nouns (things)

Re: Designing a Pragmatic RESTful API

#98

Post by bbq »

vyrotek wrote: post #44
icebraining wrote: post #29

Earlier quoted context omitted.

REST only looks complicated because you're seeing it with RPC goggles. In REST, you don't call functions, you just ask for documents and send documents to the server(s). There's nothing particularly complicated in it, it's just a different approach. That said, this article isn't particularly faithful to REST.

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.
Post reply on HN