Live data from Hacker News

Problems with RESTful APIs (2015)

mmikowski.github.io

101–110 of 224 posts

Re: Problems with RESTful APIs (2015)

#101

When I was given the task of defining how our multi-robot server would interface with our user interfaces, I eventually settled on REST. Most of what I knew about REST had been obtained that week. I implemented something pretty vanilla with Django and it all felt pretty elegant. I didn't have to worry about defining a protocol, there was pretty much already one for me: - GET, PUT, POST, DELETE (I learned there were o…

> I feel like I had success because I approached it from a position of ignorance, meaning I just implemented a simple, sane REST API and was none the wiser that I was doing it wrong.

None of it is REST though, it's just one more RPC over HTTP protocol, which is also what TFAA advertises. Though your version uses HTTP as more than a trivial transport which I guess is nice.

Re: Problems with RESTful APIs (2015)

#102

I'm going to have to call bullshit on that one. REST is one of the more successful strategies we've come up with for connecting systems, this is just another case of letting perfect stand in the way of good enough. Using GET for non-destructive operations and POST for updates and deletes is a nice, portable compromise. I've been trying hard for years to find a reason to bother with PUT, but so far I've found it not w…

> I've been trying hard for years to find a reason to bother with PUT, but so far I've found it not worth the effort. And right there, at your final sentence, you basically described why REST has more or less failed. GET and POST are useless for implementing a complete application protocol. You'd basically overload these http verbs to the point where you would implement your own protocol. And that's what most people…

>REST is nothing but loosely connected guidelines that nobody uses in the same manner.

I don't see a problem with this. In fact, I'd love it if everyone accepted this instead of whining that something isn't truly "RESTful."

For instance, the app I'm working on deliberately does not implement HATEOAS. I appreciate the academic effort behind REST and RESTfulness, but ultimately I view it only as an ideal to tend toward. As you said, it's a guideline.

Re: Problems with RESTful APIs (2015)

#103

When I was given the task of defining how our multi-robot server would interface with our user interfaces, I eventually settled on REST. Most of what I knew about REST had been obtained that week. I implemented something pretty vanilla with Django and it all felt pretty elegant. I didn't have to worry about defining a protocol, there was pretty much already one for me: - GET, PUT, POST, DELETE (I learned there were o…

> I feel like I had success because I approached it from a position of ignorance, meaning I just implemented a simple, sane REST API and was none the wiser that I was doing it wrong. None of it is REST though, it's just one more RPC over HTTP protocol, which is also what TFAA advertises. Though your version uses HTTP as more than a trivial transport which I guess is nice.

We read then manipulate the state of a multi-robot fleet by making HTTP GET, PUT, POST, DELETE calls that affect a database and robot broker/manager services. The state of the robots and the configuration of the system is represented in JSON. Interaction with the system is stateless, meaning you can jump in at any time, understand the full state of the system, and manipulate it safely. Interaction of a healthy system will involve numerous physical and virtual clients/servers, many of which are physically on the move most of the time.

If this isn't REST then the Wikipedia page on REST needs updating or I'm just not explaining it well enough.

Re: Problems with RESTful APIs (2015)

#104
REST is successful for the same reason React Native is successful.

Before REST, there was SOAP, similar in spirit to the JSON-Pure solution proposed by this author. SOAP's promise was a version of Java's "Write once, run everywhere". In the case of SOAP, this meant that if you have a SOAP client, you could consume data from any SOAP server with only the domain specific part different.

Like Java, SOAP over-promised. In practice, there was horrible incompatibility between all the different SOAP providers and consumers; people lacked features so they hacked it on to the protocol, only to discover later that the default SOAP client in $THAT_OTHER_LANGUAGE didn't allow them to consume that hack as easily as it was in the first language. And so on, and so forth.

REST, on the other side, hardly promises anything at all. In practice, most people doing a REST API agree on a rough idea of what URLs look like, and yes let's do our best and embrace HTTP verbs and status codes. In a way, REST is "learn once, use everywhere" - not unlike React Native's motto.

This became wildly successful because the clients were all compatible from the start (after all, HTTP was widespread already). Compared the SOAP and most RPC setups, the clients are super underpowered; you need to do a bit of extra work. The only way to know what URLs to compose is to read the API docs (because HATEOAS is beautiful in theory only). The data is often JSON but maybe not, and you're again going to have to pay attention to the docs.

In practice, though, it keeps the developer firmly in control. Most developers using REST actually understand the entire protocol. They know enough HTTP to be dangerous, they can look at what goes over the line and it makes sense. The moment you add more features to the protocol, you just make it more complicated and obtuse.

I'm not convinced that's a way forward, not without serious (GraphQL-level) benefits.

Re: Problems with RESTful APIs (2015)

#105
post #99

From the article: "The way forward: JSON-Pure APIs" . I can see a little of this. It's better today to send parameters in HTTP data in JSON format rather than encoding them in the URL. If you're doing a pure GET, you can send parameters with the URL, but anything that changes server side state probably shouldn't be done that way. Of course, what's happening is that the JSON crowd is re-inventing SOAP, but, whatever.

> Of course, what's happening is that the JSON crowd is re-inventing SOAP, but, whatever.

SOAP uses schemas and the like, they just keep reinventing the same RPC as ever, except can't actually bring themselves to use the word. At least JSON-RPC is honest there, and ticks all of TFAA's box:

* uses whatever's under as a trivial transport (covers 1, 3 and 6)

* all data and metadata are part of the higher protocol (covers 2, 4 and 5)

* is JSON (covers the entire essay)

Re: Problems with RESTful APIs (2015)

#106

Earlier quoted context omitted.

> I feel like I had success because I approached it from a position of ignorance, meaning I just implemented a simple, sane REST API and was none the wiser that I was doing it wrong. None of it is REST though, it's just one more RPC over HTTP protocol, which is also what TFAA advertises. Though your version uses HTTP as more than a trivial transport which I guess is nice.

We read then manipulate the state of a multi-robot fleet by making HTTP GET, PUT, POST, DELETE calls that affect a database and robot broker/manager services. The state of the robots and the configuration of the system is represented in JSON. Interaction with the system is stateless, meaning you can jump in at any time, understand the full state of the system, and manipulate it safely. Interaction of a healthy system…

I agree that the communication you described isn't completely REST style but rather "just" using HTTP as an application protocol. There is no real downside in doing so but it shouldn't be called REST.

REST based on the Richardson maturity model[1] involves:

Level 0: Using HTTP as the transport protocol: e.g. SOAP

Level 1: Identifiable objects: e.g. /object/object_id

Level 2: Using HTTP as the application protocol: e.g. Using POST to create new objects and DELETE to remove them

Level 3: HATEOAS

[1] https://martinfowler.com/articles/richardsonMaturityModel.ht...

Re: Problems with RESTful APIs (2015)

#107
post #106

Earlier quoted context omitted.

We read then manipulate the state of a multi-robot fleet by making HTTP GET, PUT, POST, DELETE calls that affect a database and robot broker/manager services. The state of the robots and the configuration of the system is represented in JSON. Interaction with the system is stateless, meaning you can jump in at any time, understand the full state of the system, and manipulate it safely. Interaction of a healthy system…

I agree that the communication you described isn't completely REST style but rather "just" using HTTP as an application protocol. There is no real downside in doing so but it shouldn't be called REST. REST based on the Richardson maturity model[1] involves: Level 0: Using HTTP as the transport protocol: e.g. SOAP Level 1: Identifiable objects: e.g. /object/object_id Level 2: Using HTTP as the application protocol: e.…

I'm not sure where I misguided people that I was just doing RPC. Almost all endpoints are as you described:

`/robots/robot_id/exceptions`

`/maps/map_id/destinations`

`/maps/map_id/areas/speed_limit_areas`

Performing operations is not done via. RPC but rather POSTing a new `mission` to the queue.

There's no HATEOS but that would generally be silly, since this isn't an API that requires easy discovery and consumption by third parties. I'm not sure I subscribe to the HATEOS required for REST, but I don't really care to argue.

I think I'm starting to get a sense that people can be really opinionated on this stuff, and I'm still lost as to what there is to gain by it. To suggest what I'm describing isn't REST would be to say that the first sections of the Wikipedia page are wrong. So are we so far off-base that we need to revise the Wikipedia page? Or is this more just an opinion?

Thanks for sharing your thoughts. Maybe there's a chance to de-mystify my confusion on why there's so many opinions on something that, to me, seems so simple to define.

Re: Problems with RESTful APIs (2015)

#108

On first pass, I totally agree with the author. I haven't reviewed the proposed alternative yet but fingers crossed. That said, I think he misses the single biggest issue with REST APIs that I continuously encounter and which has caused me to consider them sub-par. Representative "State" Transfer. REST APIs are only good for transferring around the state of stateful objects. However, CRUD operations are only part of…

REST provides no identifiable mechanism for performing actions outside of CRUD operations and is, therefore, a completely impractical solution.

The mechanism is identifiable once you start to really think in REST terms. The problem is that people think in RPC, and so try to shove its model instead.

REST is based on names (resources), not commands. Therefore, we must implement our actions as resources. Instead of having a "transfer()" command, you have a Transfer resource type, which you create to start one. Eg:

  POST /transfers ... (Body describes parameters)
  201 Created, Location: /transfers/34
This change from a command to a resource additionally provides the benefits of REST, necessary for communication over an unreliable network: rather than keep your connection open while the action is processed, you get an URL you can poll to check if it is finished. This works even if the client goes offline for some time.

Re: Problems with RESTful APIs (2015)

#109
post #96

> most client and server applications don’t support all verbs or response codes for the HTTP protocol. For example, most web browsers have limited support for PUT or DELETE. And many server applications often don’t properly support these methods either. I have never, as in ever, stumbled upon this problem. So I googled it. It turns out that what he means is that HTML forms don't support PUT and DELETE. In a world whe…

To be fair, the verbs can feel a little weird.

GET is easy.

HEAD is easy.

DELETE is easy.

PATCH is easy, especially when you use one of the two more useful standards (RFC 7386: JSON Merge Patch, or RFC 6902: JSON Patch).

PUT is not much use for large resources (like those typically found in business systems) since it requires you to provide every field, but usually you would want the back end to assign at the last the primary identifier, date created, etc. I seem to remember reading that even Roy felt PUT was not well designed.

POST is a catch all for any other update/insert type activity.

To paraphrase Winston Churchill, "http verbs are a poor system, but better than all the other systems that have been tried from time to time."

Re: Problems with RESTful APIs (2015)

#110
post #106

Earlier quoted context omitted.

I agree that the communication you described isn't completely REST style but rather "just" using HTTP as an application protocol. There is no real downside in doing so but it shouldn't be called REST. REST based on the Richardson maturity model[1] involves: Level 0: Using HTTP as the transport protocol: e.g. SOAP Level 1: Identifiable objects: e.g. /object/object_id Level 2: Using HTTP as the application protocol: e.…

I'm not sure where I misguided people that I was just doing RPC. Almost all endpoints are as you described: `/robots/robot_id/exceptions` `/maps/map_id/destinations` `/maps/map_id/areas/speed_limit_areas` Performing operations is not done via. RPC but rather POSTing a new `mission` to the queue. There's no HATEOS but that would generally be silly, since this isn't an API that requires easy discovery and consumption b…

> I'm not sure where I misguided people that I was just doing RPC.

Sadly the person you respond to is an idiot, their points 1 and 3 have literally nothing to do with REST. You could have all endpoints be /435645646 yet do rest, you can have the most beautifully crafted URLs in the world and do rpc, they're orthogonal concerns. Most people do the latter, incidentally.

> Performing operations is not done via. RPC but rather POSTing a new `mission` to the queue.

That's still RPC. Encoding your procedure calls via HTTP verbs doesn't make it not RPC, it makes it (as originally noted) leverage HTTP as more than a trivial transport.

> There's no HATEOS

So it's not REST, HATEOAS/hyperlinking is the one thing that qualifies your API as REST according to the bloke who originally defined that term: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

> I think I'm starting to get a sense that people can be really opinionated on this stuff

Well yeah imagine you see a nice essay defining or formalising a concept (hyperlinked application interfaces) and creating a word/acronym for it (REST), then you see the world around it coopt it without any of the meaning to qualify something which already existed but has seemingly fallen out of fashion (RPC in this case). That's bothersome.

> seems so simple to define.

If your simple definition of REST is just that you're using HTTP, why would you need a separate acronym for it?

Post reply on HN