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

Most RESTful APIs aren't really RESTful

florian-kraemer.net

Post reply on HN
Print view View original

71–80 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#71

Post by mort96 »

ewuhic wrote: post #65
mort96 wrote: post #62

Earlier quoted context omitted.

Why should I (or you, for that matter) go and tell them their restful has nothing to do with rest? Why does it matter? They're making perfectly fine HTTP APIs, and they use the industry standard term to describe what kind of HTTP API it is. It's convenient to have a word for "HTTP API where entities are represented by JSON objects with unique paths, errors are communicated via HTTP status codes and CRUD actions use t…

1. Never said I'm going to tell them. It's on someone else. I'm just going to lower my expectation from such developers accordingly. 2. So just "HTTP API". And that would suffice. Adding "restful" is trying to be extra-smart or fit in if everyone's around an extra-smart.

> 1. Never said I'm going to tell them. It's on someone else. I'm just going to lower my expectation from such developers accordingly.

This doesn't seem like a useful line of conversation, so I will ignore it.

> 2. So just "HTTP API".

No! There are many kinds of HTTP APIs. I've both made and used "HTTP APIs" where HTTP is used as a transport and API semantics are wholly defined by the message types. I've seen APIs where every request is an HTTP POST with a protobuf-encoded request message and every response is a 200 OK with a protobuf-encoded response message (which might then indicate an error). I've seen GraphQL APIs. I've seen RPC-style APIs where every "RPC call" is a POST requset to an endpoint whose name looks like a function name. I've seen APIs where request and response data is encoded using multipart/form-data.

Hell, even gRPC APIs are "HTTP APIs": gRPC uses HTTP/2 as a transport.

Telling me that something is an "HTTP API" tells me pretty much nothing about how it works or how I'm expected to use it, other than that HTTP is in some way involved. On the other hand, if you tell me that something is a "REST API", I already have a very good idea about how to use it, and the documentation can assume a lot of pre-existing context because it can assume that I've used similar APIs before.

Re: Most RESTful APIs aren't really RESTful

#72

Post by ivan_gammel »

Scarblac wrote: post #5

UI designers want control over the look of the page in detail. E.g. some actions that can be taken on a resource are a large button and some are hidden in a menu or not rendered in the UI at all. A client application that doesn't have any knowledge about what actions are going to be possible with a resource, instead rendering them dynamically based on the API responses, is going to make them all look the same. So RES…

This is wrong on many levels.

1. UX designers operate on every stage of software development lifecycle from product discovery to post-launch support (validation of UX hypotheses), they do not exercise control - they work within constraints as part of the team. The location of a specific action in UI and interaction triggering it is orthogonal to availability of this action. Availability is defined by the state. If state restricts certain actions, UX must reflect that.

2. From architectural point of view, once you encapsulate the checking state behavior, the following will work the same way: "if (state === something)" and "if (resource.links["action"] !== null)". The latter approach will be much better, because in most cases any state-changing actions will require validation on server and you can implement the logic only once (on server).

I have been developing HATEOAS applications for quite a while and maintain HAL4J library: there are some complexities in this approach, but UI design is certainly not THE problem.

Re: Most RESTful APIs aren't really RESTful

#73

Post by 2muchcoffeeman »

kitd wrote: post #63
ewuhic wrote: post #59

Earlier quoted context omitted.

The point is lost on you though. There are REST APIs (almost none), and there are "REST APIs" - a battle cry of mediocre developers. Now go tell them their restful has nothing to do with rest. And I am now just repeating stuff said in article and in comments here.

I think the pushback is because you labelled people who create "REST APIs" as "mediocre" without any explanation. That may be a good starting point.

It’s the worst kind of pedantry. Simultaneously arrogant, uncharitable and privileged.

Most of us are not writing proper Restful APIs because we’re dealing with legacy software, weird requirements the egos of other developers. We’re not able to build whatever we want.

And I agree with the feature article.

Re: Most RESTful APIs aren't really RESTful

#74

Post by motorest »

mort96 wrote: post #71
ewuhic wrote: post #65

Earlier quoted context omitted.

1. Never said I'm going to tell them. It's on someone else. I'm just going to lower my expectation from such developers accordingly. 2. So just "HTTP API". And that would suffice. Adding "restful" is trying to be extra-smart or fit in if everyone's around an extra-smart.

> 1. Never said I'm going to tell them. It's on someone else. I'm just going to lower my expectation from such developers accordingly. This doesn't seem like a useful line of conversation, so I will ignore it. > 2. So just "HTTP API". No! There are many kinds of HTTP APIs. I've both made and used "HTTP APIs" where HTTP is used as a transport and API semantics are wholly defined by the message types. I've seen APIs wh…

> On the other hand, if you tell me that something is a "REST API", I already have a very good idea about how to use it (...)

Precisely this. The value of words is that they help communicate concepts. REST API or even RESTful API conveys a precise idea. To help keep pedantry in check, Richardson's maturity model provides value.

Everyone manages to work with this. Not those who feel the need to attack people with blanket accusations of mediocrity, though. They hold onto meaningless details.

Re: Most RESTful APIs aren't really RESTful

#75

Post by Scarblac »

TekMol wrote: post #38
Scarblac wrote: post #31

Earlier quoted context omitted.

Bots, browsers that preload URLs, caching (both browser and backend and everything in between), the whole infrastructure of the Web that assumes GET never mutates and is always safe to repeat or serve from cache. Using GET also circumvents browser security stuff like CORS, because again the browser assumes GET never mutates.

So why is there no problem with vote/flag/vouche on HN being GET endpoints?

There is, it's bad. Luckily votes aren't very crucial.

Re: Most RESTful APIs aren't really RESTful

#76

Post by dwaltrip »

I'll never understand why the HATEOAS meme hasn't died.

Is anyone using it? Anywhere?

What kind of magical client can make use of an auto-discoverable API? And why does this client have no prior knowledge of the server they are talking to?

Re: Most RESTful APIs aren't really RESTful

#77

Post by motorest »

2muchcoffeeman wrote: post #73
kitd wrote: post #63

Earlier quoted context omitted.

I think the pushback is because you labelled people who create "REST APIs" as "mediocre" without any explanation. That may be a good starting point.

It’s the worst kind of pedantry. Simultaneously arrogant, uncharitable and privileged. Most of us are not writing proper Restful APIs because we’re dealing with legacy software, weird requirements the egos of other developers. We’re not able to build whatever we want. And I agree with the feature article.

> It’s the worst kind of pedantry. Simultaneously arrogant, uncharitable and privileged.

I'd go as far as to claim it is by far the dumbest kind, because it has no value, serves no purpose, and solves no problem. It's just trivia used to attack people.

Re: Most RESTful APIs aren't really RESTful

#78

Post by motorest »

dwaltrip wrote: post #76

I'll never understand why the HATEOAS meme hasn't died. Is anyone using it? Anywhere? What kind of magical client can make use of an auto-discoverable API? And why does this client have no prior knowledge of the server they are talking to?

I think OData isn't used, and that's a proper standard and a lower bar to clear. HATEOAS isn't even benefiting from a popular standard, which is both a cause and a result.

Re: Most RESTful APIs aren't really RESTful

#79

Post by okr »

runroader wrote: post #66
ewuhic wrote: post #50

Earlier quoted context omitted.

[flagged]

This is more like people arguing over "proper" English, the point of language is to communicate ideas. I work for a German company and my German is not great but if I can make myself understood, that's all that's needed. Likewise, the point of an API is to allow programs, systems, and people to interoperate. If it accomplishes that goal, it's fine and not worth fighting over. If my API is supposed to rely on content-…

I agree, thought it would be really really nice if a http method like GET would not modify things. :)

Re: Most RESTful APIs aren't really RESTful

#80

Post by TekMol »

Scarblac wrote: post #57
TekMol wrote: post #46

Earlier quoted context omitted.

The same would have worked with a POST endpoint. The story url only would have to point to a web page that creates the upvote post request via JS.

That runs into CORS protections though. CORS is a lot less strict around GET as it is supposed to be safe.

Nope, it would not have been prevented by CORS.

CORS prevents reading from a resource, not from sending the request.

If you find that surprising, think about that the JS could also have for example created a form with the vote page as the target and clicked on the submit button. All completely unrelated to CORS.

Post reply on HN