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

Problems with Swagger

blog.novatec-gmbh.de

Post reply on HN
Print view View original

81–90 of 163 posts

Re: Problems with Swagger

#81

Post by edmccard »

eterps wrote: post #55
richardwhiuk wrote: post #48

Earlier quoted context omitted.

If I remove the reference to a link in the response, it doesn't remove the clients need to: a) know how to retrieve that link (i.e. what resource do I need to retrieve in order to get that response) b) requirement for that link to exist (they still need that link). Requiring that a client know that to get data Bar, they need to retrieve resource A, follow the link at foo[n]._link to retrieve resource B, and then foll…

I am not sure I get your example. But yes the client still has to know what to do in advance.

>But yes the client still has to know what to do in advance.

According to Roy Fielding[1] (who came up with the concepts of ReST and HATEOAS:

"A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience"

So if an application doesn't rely on "standardized media types", and "the client still has to know what to do in advance", then it seems like whatever you're doing, it isn't HATEOAS after all.

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Re: Problems with Swagger

#82

Post by icebraining »

richardwhiuk wrote: post #45
xienze wrote: post #24

Earlier quoted context omitted.

> It's impossible for me to see how it would be possible to write a HATEOAS client, and I can't in practice see anyone doing so. There's nothing complicated about a client that understands Hypermedia links. You start at the root, it'll give you a set of links to follow, and you recurse. Here's a browser that can take a HATEOAS-compatible API and will let you work your way through the API: http://dracoblue.github.io/h…

I meant a user friendly client, not something aimed at API developers. Sure you can create something which is aimed at Developers, but it's not presenting the data in a way any user would understand, or in a way that a UX expert can flex. Fundamentally, your display logic should not be linked to your API schema, but HATEOAS essentially enforces that, because you can't predict what links will be available.

your display logic should not be linked to your API schema

Why not? The whole point of HATEOAS is to design your API schema in function of your application flow. You know, just like we do on websites.

Re: Problems with Swagger

#83

Post by wstrange »

querulous wrote: post #42
richardwhiuk wrote: post #16

Earlier quoted context omitted.

I agree that HATEOAS is never deployed anywhere, but I think I'd go further than that. It's impossible for me to see how it would be possible to write a HATEOAS client, and I can't in practice see anyone doing so. Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong metrics, and a complete waste of development time and effort.

every web browser you use is a hateoas client you get some html with embedded links and then the browser automatically goes and fetches css, js, images... the remaining links it just presents to you, the user, to follow or not as you choose hateoas is not a complicated idea. it's not meant to replace SOAP or gRPC or thrift. it's something else

The browser is driven by advanced AI wetware that understands the semantics of the data and can make decisions on what to do next.

I think REST/HATEOAS purists have always overplayed the browser example.

Pure machine to machine interaction is hard to automate.

Re: Problems with Swagger

#84

Post by icebraining »

ajross wrote: post #56
querulous wrote: post #42

Earlier quoted context omitted.

every web browser you use is a hateoas client you get some html with embedded links and then the browser automatically goes and fetches css, js, images... the remaining links it just presents to you, the user, to follow or not as you choose hateoas is not a complicated idea. it's not meant to replace SOAP or gRPC or thrift. it's something else

Except the browser really isn't. It has strict behavior, and the list of what happens as it loads that hypermedia is deterministic and known to both the client and server. The difference between what happens when the browser sees a "stylesheet" link reference and a "icon" one is significant, and not something the browser is expected to figure out on its own. The HATEOAS idea is that you throw that out, just use some…

I think you have a completely wrong idea about HATEOAS. The application is certainly expected to be able to handle the data format, not figure out by magic. As Fielding writes in his dissertation, REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types. The client is certainly supposed to understand these data types, that's why they must be standard (like HTML). The dynamic part comes from the formats themselves, which may have variable or optional elements depending on the state of the resource.

Re: Problems with Swagger

#85

Post by icebraining »

cookiecaper wrote: post #72
soofaloofa wrote: post #63

Earlier quoted context omitted.

I'm not even sure what you mean. RPC is fundamentally different than REST and I don't know how you can layer on over top of the other?

RPC is not fundamentally different from REST. REST is a form of RPC. (/me ducks tomatoes thrown among boos and hisses from the crowd) The difference is that the processes behind REST speak with HTTP. You're still doing a "remote procedure call"; you're asking for a remote process to execute some function on your behalf and return the result. RPCs facilitate the same exact thing. How is this a "fundamental" difference…

RPC doesn't have an Uniform Interface.

Say you have a user profile, which has a Gravatar associated. Sure you can have a getUserProfile() procedure that fetches the user information, but what about the image? You can write a getUserAvatar() procedure that proxies it, but that's wasteful.

In a RESTful system, you have a Resource Identifier (URL) that you can indicate as an hypermedia reference (link), with which the client can use a standard data fetching verb (GET) to retrieve it directly from the other server.

Of course, in a practical setting the getUserProfile() procedure would return the URL, but that's just an admission of the limitations of RPC vis-a-vis REST.

On the other hand, REST itself has its own problems and limitations, and is certainly not adequate for every use case, as Fielding's dissertation mentions at length.

Re: Problems with Swagger

#86

Post by ajross »

icebraining wrote: post #84
ajross wrote: post #56

Earlier quoted context omitted.

Except the browser really isn't. It has strict behavior, and the list of what happens as it loads that hypermedia is deterministic and known to both the client and server. The difference between what happens when the browser sees a "stylesheet" link reference and a "icon" one is significant, and not something the browser is expected to figure out on its own. The HATEOAS idea is that you throw that out, just use some…

I think you have a completely wrong idea about HATEOAS. The application is certainly expected to be able to handle the data format, not figure out by magic. As Fielding writes in his dissertation, REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types . The client is certainly supposed to understand these data types, that's why the…

Someone needs to fix the wikipedia page on HATEOAS then, because it says exactly the opposite of what you just did in its third sentence.

(One of the other problems with Fielding's work is precisely this word-salad of new jargon and usages, leading to exactly this kind of what-does-it-REALLY-mean-anyway confusion. But that's an argument for a different thread.)

Re: Problems with Swagger

#87

Post by icebraining »

ajross wrote: post #86
icebraining wrote: post #84

Earlier quoted context omitted.

I think you have a completely wrong idea about HATEOAS. The application is certainly expected to be able to handle the data format, not figure out by magic. As Fielding writes in his dissertation, REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types . The client is certainly supposed to understand these data types, that's why the…

Someone needs to fix the wikipedia page on HATEOAS then, because it says exactly the opposite of what you just did in its third sentence. (One of the other problems with Fielding's work is precisely this word-salad of new jargon and usages, leading to exactly this kind of what-does-it-REALLY-mean-anyway confusion. But that's an argument for a different thread.)

From the wikipedia page: "The media types used for these representations, and the link relations they may contain, are standardized."

As for Fielding's work having a word-salad of new jargon and uses, I frankly didn't get that by reading his dissertation, which I found quite clear. There are a few concepts (Resources, Representations), but I think they make sense in the context.

Re: Problems with Swagger

#88

Post by cookiecaper »

icebraining wrote: post #85
cookiecaper wrote: post #72

Earlier quoted context omitted.

RPC is not fundamentally different from REST. REST is a form of RPC. (/me ducks tomatoes thrown among boos and hisses from the crowd) The difference is that the processes behind REST speak with HTTP. You're still doing a "remote procedure call"; you're asking for a remote process to execute some function on your behalf and return the result. RPCs facilitate the same exact thing. How is this a "fundamental" difference…

RPC doesn't have an Uniform Interface. Say you have a user profile, which has a Gravatar associated. Sure you can have a getUserProfile() procedure that fetches the user information, but what about the image? You can write a getUserAvatar() procedure that proxies it, but that's wasteful. In a RESTful system, you have a Resource Identifier (URL) that you can indicate as an hypermedia reference (link), with which the c…

REST doesn't have a uniform interface in practice, either.

I haven't read the dissertation so I can't really comment on the hypothetical REST (though it is on my reading list now, and not that it really stops anyone else), I can only comment on what, in the real world, passes for a "REST API".

"REST" principles certainly sound nice on paper, but for the most part, it's clear that they're completely implausible to realize in a wide-scale, meaningful way. After over a decade of pro-REST propaganda, people still can't even tell if their interface is "RESTful" or not.

The parts of "REST" that have worked are the two simple basics of HTTP: GETting a resource to read it, or POSTing a resource to write it. Nothing else has really stuck or can be expected to have a uniform meaning (and even POST's behavior will vary, with some doing an upsert-style operation and some accepting it only for new writes and using PUT and/or PATCH for edits). 200 OK means it worked most of the time, but sometimes people will return a plaintext error with it. 404 might mean that the resource is not found, or it might mean that the route is not found/no longer valid (or that it was called with invalid or improperly encoded parameters). There are a bunch of esoteric codes that are used to mean a lot of different things, always depending on who the implementer is.

So the "uniform interface" is just that everyone is using HTTP, to mean all sorts of different things. In practical terms, it doesn't really amount to much, except a lot of blathering over whether something conforms with a theoretical ideal that everyone has already demonstrated they're unwilling to conform to.

Re: Problems with Swagger

#90

Post by cookiecaper »

sebular wrote: post #64
cookiecaper wrote: post #50

Earlier quoted context omitted.

How about urllib, the Python default? def handle_thing(thing): r = urllib.request.Request(url='example.com', data={'stuff': 1}) return urllib.request.urlopen(r) Just one example. I know the tooling has improved somewhat since REST has become extremely common, so this is less of an issue now than it used to be (for example, most people use the Python requests module now, which makes it harder to use the wrong method (…

You're going on about the value of "conventional methods" in a criticism of using HTTP verbs? Understanding the difference between a GET and a POST isn't some new-fangled idea, it's decades old. Like Tim Berners Lee old. I didn't even know what Thrift was until I Googled it, and found out it was developed at Facebook. Okay. I'm stunned. Do you write code that runs on the internet? How did you even get employed?

The edit timeout is expired on my other comment, but it just occurred to me that, since you were unfamiliar with what is arguably the most-used IDL today, you may not understand that interface definition language like Thrift defines the interface, not just the objects. You'll have a section like (adapted from the Apache Thrift tutorial file [0])

    service Calculator extends shared.SharedService {
       void ping(),
       i32 add(1:i32 num1, 2:i32 num2),
       i32 calculate(1:i32 logid, 2:Work w) throws (1:InvalidOperation ouch)
    }
which lists the method name, parameters and types, return type, and possible exceptions. The objects are defined elsewhere in the file (or in an include). The method name is not just a value that is randomly assigned by the developer (and how could it be? the interface has to name the things so they can be referenced).

To be a firm REST religionist, as you seem to be, you must not have worked with it very often, but you can see that an actual IDL, and Thrift is just one of several, would make things much easier than the loose "My REST is purer than your REST" dick-measuring contests.

[0] https://git-wip-us.apache.org/repos/asf?p=thrift.git;a=blob_...

Post reply on HN