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

271–280 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#271

Post by cjpearson »

meehai wrote: post #193
cjpearson wrote: post #40

I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. When I see "REST API" I can safely assume the following: - The API returns JSON - CRUD actions are mapped to POST/GET/PUT/DELETE - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec - There's a decent chance listing endpoints were changed to POST to su…

the last point got me. How can you idiomatically do a read only request with complex filters? For me both PUT and POST are "writable" operations, while "GET" are assumed to be read only. However, if you need to encode the state of the UI (filters or whatnot), it's preferred to use JSON rather than query params (which have length limitations). So ... how does one do it?

Soon, hopefully, QUERY will save us all. In the meantime, simply using POST is fine.

I've also seen solutions where you POST the filter config, then reference the returned filter ID in the GET request, but that often seems like overkill even if it adds some benefits.

Re: Most RESTful APIs aren't really RESTful

#272

Post by cratermoon »

cjpearson wrote: post #40

I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. When I see "REST API" I can safely assume the following: - The API returns JSON - CRUD actions are mapped to POST/GET/PUT/DELETE - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec - There's a decent chance listing endpoints were changed to POST to su…

> The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec

I've done this enough times that now I don't really bother engaging. I don't believe anyone gets it 100% correct ever. As long as there is nothing egregiously incorrect, I'll accept whatever.

Re: Most RESTful APIs aren't really RESTful

#273

Post by naasking »

mixedbit wrote: post #245
naasking wrote: post #217

Earlier quoted context omitted.

> For things like debugger, REPL, or some database inspection/manipulation tool, this approach is useful, but for most apps exposed to end users Yes, exactly, but the point is that something like Swagger becomes completely trivial, and so you no longer need a separate, complex tool to do what the web automatically gives you. The additional benefits are on the server-end, in terms of maintenance and service flexibilit…

There are many ideas in the REST paper that are super useful, but the goal of making a generic client working with any API is difficult if not impossible to achieve. Was the client of the service that you worked on fully generic and application independent? It is one thing to be able to change URLs only on the server, without requiring a client code change, and such flexibility is indeed practical benefit that the RE…

> There are many ideas in the REST paper that are super useful, but the goal of making a generic client working with any API is difficult if not impossible to achieve.

It's definitely possible to achieve: anywhere that data is missing you present an input prompt, which is exactly what a web browser does.

That said, the set of autonomous programs that can do something useful without knowing what they're doing is of course more limited. These are generic programs like search engines and AI training bots that crawl and index information.

> It is another thing to change say, a calendar application into a messaging application just by returning a different entry point URL to the same generic client code.

Web browsers do exactly this!

Re: Most RESTful APIs aren't really RESTful

#274

Post by marcosdumay »

Cthulhu_ wrote: post #130
cjpearson wrote: post #40

I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. When I see "REST API" I can safely assume the following: - The API returns JSON - CRUD actions are mapped to POST/GET/PUT/DELETE - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec - There's a decent chance listing endpoints were changed to POST to su…

HTTP/JSON API works too, but you can assume it's what they mean by REST. It makes me wish we stuck with XML based stuff, it had proper standards, strictly enforced by libraries that get confused by things not following the standards. HTTP/JSON APIs are often hand-made and hand-read, NIH syndrone running rampant because it's perceived to be so simple and straightforward. To the point of "we don't need a spec, you can…

> it had proper standards

Lol. Have you read them?

SOAP in particular can really not be described as "proper".

It had the advantage that the API docs were always generated, and thus correct, but the most common thing is for one software stack not being able to use a service built with another stack.

Re: Most RESTful APIs aren't really RESTful

#275

Post by mixedbit »

Balooga wrote: post #237
mixedbit wrote: post #47

When I was working on my first HTTP-based API 13 years ago, based on many comments about true REST, I decided to first study what REST should really be. I've read Fielding's paper cover to cover, I've read RESTful Web Services Cookbook from O'Reilly and then proceeded to workaround Django idioms to provide REST API. This was a bit cargo cult thinking from my end, I didn't truly understand how REST would benefit my se…

> Fielding's paper doesn't provide a complete recipe for building self-discoverable APIs. But it does though. A HTTP server returns a HTTP response to a request from a browser. The request is a HTML webpage that is rendered to the user with all discoverable APIs visible as clickable links. Welcome to the World Wide Web.

You describe how web pages work, web pages are intended for human interactions, APIs are intended for machine interaction. How a generic Python or JavaScript client can discover these APIs? Such clients will request JSON representation of a resource, because JSON is intended for machine consumption, HTML is intended for humans. Representations are equivalent, if you request JSON representations of a /users resource, you get a JSON list. If you request HTML representation of a /users resource you get an HTML list, but the content should be the same. Should you return UI controls for modifying a list as part of the HTML representation? If you do so, your JSON and HTML representations are different, and your Python and JavaScript client still cannot discover what list modification operations are possible, only human can do it by looking at the HTML representation. This is not REST if I understand the paper correctly.

Re: Most RESTful APIs aren't really RESTful

#276

Post by motorest »

troupo wrote: post #266
motorest wrote: post #263

Earlier quoted context omitted.

> Nowhere is JSON in the name of REpresentational State Transfer. If you read the message you're replying to, you'll notice you are commenting on the idea of coining the concept of HTTP/JSON API as a better fitting name.

Read messages before replying? It's the internet! Ain't no one got time for that :)

Don't stress it. It happens to the best of us.

Re: Most RESTful APIs aren't really RESTful

#277

Post by rswail »

meehai wrote: post #193
cjpearson wrote: post #40

I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. When I see "REST API" I can safely assume the following: - The API returns JSON - CRUD actions are mapped to POST/GET/PUT/DELETE - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec - There's a decent chance listing endpoints were changed to POST to su…

the last point got me. How can you idiomatically do a read only request with complex filters? For me both PUT and POST are "writable" operations, while "GET" are assumed to be read only. However, if you need to encode the state of the UI (filters or whatnot), it's preferred to use JSON rather than query params (which have length limitations). So ... how does one do it?

HTML FORMs are limited to www-form-encoded or multipart. The length or the queries on a GET with a FORM is limited by intermediaries that shouldn't be limiting it. But that's reality.

Do a POST of a query document/media type that returns a "Location" that contains the query resource that the server created as well as the data (or some of it) with appropriate link elements to drive the client to receive the remainder of the query.

In this case, the POST is "writing" a query resource to the server and the server is dealing with that query resource and returning the resulting information.

Re: Most RESTful APIs aren't really RESTful

#278

Post by Deukhoofd »

akvadrako wrote: post #267
CSMastermind wrote: post #244

Earlier quoted context omitted.

Lots of people make PUTs that work like PATCHes and it drives me crazy. Same with people who use POST to retrieve information.

Well you can't reliably use GET with bodies. There is the proposed SEARCH but using custom methods also might not work everywhere.

The SEARCH verb draft was superseded by the QUERY verb draft last I checked. QUERY is somewhat more adopted, though it's still very new.

Re: Most RESTful APIs aren't really RESTful

#279

Post by harha_ »

Cthulhu_ wrote: post #130
cjpearson wrote: post #40

I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. When I see "REST API" I can safely assume the following: - The API returns JSON - CRUD actions are mapped to POST/GET/PUT/DELETE - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec - There's a decent chance listing endpoints were changed to POST to su…

HTTP/JSON API works too, but you can assume it's what they mean by REST. It makes me wish we stuck with XML based stuff, it had proper standards, strictly enforced by libraries that get confused by things not following the standards. HTTP/JSON APIs are often hand-made and hand-read, NIH syndrone running rampant because it's perceived to be so simple and straightforward. To the point of "we don't need a spec, you can…

I recall having to maintain an integration to some obscure SOAP API that ate and spit out XML with strict schemas and while I can't remember much about it, I think the integration broke quite easily if the other end changed their API somehow.

Re: Most RESTful APIs aren't really RESTful

#280

Post by rswail »

blueflow wrote: post #203
shagie wrote: post #194

Earlier quoted context omitted.

POST the filter, get a response back with the query to follow up with for the individual resources. POST /complex value1=something value2=else which then responds with 201 Created Location https://example.com/complex/53301a34-92d3-447d-ac98-964e9a8b3989 And then you can make GET request calls against that resource. It adds in some data expiration problems to be solved, but its reasonably RESTful.

This has RESTful aesthetics but it is a bit unpractical if a read-only query changes state on the server, as in creating the uuid-referenced resource.

There's no requirement in HTTP (or REST) to either create a resource or return a Location header.

For the purposes of caching etc, it's useful to have one, as well as cache controls for the query results, and there can be links in the result relative to the Location (eg a link href of "next" is relative to the Location).

Post reply on HN