Hacker News Reader

Comment by cxr | Hacker News Reader

Fairly sure these docs are out of date wrt to the behavior of file extensions. Kyle infamously flipped an nginx switch last year to strip .html file extensions to give sites "clean URLs" (so if you have, for example, "/cyberspace/archive-the-web.html", it will give a 301 redirect to "/cyberspace/archive-the-web"), which is described in the latest Neocities blog post and unfortunately breaks the invariants that are expected by scripts and tools aimed at working with static sites.

(And, of course, as it generally goes without saying when someone labels something a "REST API", this is not REST, but that's a different topic.)

View on HN

> this is not REST

I feel like almost every API could have this footnote.

What makes most APIs not REST?

When people are being pedantic, "REST" refers specifically to a set of architectural guidelines for application and API design, including things like statelessness and HATEOAS[1]. Most "REST" APIs don't adhere to these, and are just endpoints for shoving JSON around (sometimes with idiomatic HTTP verbs).

But this is pedantry. REST has become a generic term for "shoving JSON around," for better or worse.

[1]: https://en.wikipedia.org/wiki/HATEOAS

In the case of this one you have a POST to delete and a POST to upload. Instead of POST, PUT, and DELETE requests. Thats just from a quick glance.

Most of them fail to meet one of the requirements in the "uniform interface" section; generally, in my experience, either "self-descriptive messages" or "HATEOAS".

REST is the “agile” of API design. Everyone says they do it, but everyone does it a little differently, and nobody adheres to the actual definition (because the actual definition is far too prescriptive to be fully applicable in reality)

What is REST?

It's the think that killed SOAP (and thank goodness it did).

This non-answer is about on par, where evasiveness is concerned, as the previous comment that I was responding to.

What's REST? What makes most APIs not REST?

Getting into deep pedantry here but I’m amused by the suggestion that the following is “too prescriptive”:

Individuals and interactions over processes and tools

Working software over comprehensive documentation

Customer collaboration over contract negotiation

Responding to change over following a plan

That is, while there is value in the items on the right, we value the items on the left more.

Yes. Agile is very malleable. SCRUM, which is what I assume the comment you're responding to means, is just one heavily prescriptive implementation of Agile. Of course these days people generally mean "SCRUM" when they say "Agile" which is likely due to many orgs blindly adopting the former. It's unfortunate but it is what it is, I guess.

Aren't you supposed to use an index.html in the "/cyberspace/archive-the-web/" directory to get a URL like that? And if you wanted .html files to show up like that, the nginx try-files directive could just check if the URL would work if it had a .html on the end and do an internal redirect. (like how the default config on debian adds a / to the end, if that would work)

From my experience using nginx for amateur reasons, this seems like the wrong way to go about this. Not to mention the distaste I have for caching redirects, like 301. (they make fixing your config annoying, since browsers will redirect (and switch the verb to GET) before even hitting the server)

how do you deal with id changes/renames in actual rest?

Have an internal ID and one "public" ID. The public one can be mutated with PUT/PATCH calls that are idempotent, the internal ID never ever changes.

that's technically a title change.

real world systems might have to change actual ids. like the article. or say you grow to some other use case not covered before because of new regulation etc... 301 is the only rest way.

Reply on news.ycombinator.com