48 ms·

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 follo

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 support complex filters Like Agile, CI or DevOps you can insist on the original definition or submit to the semantic diffusion and use the terms as they are commonly understood.

ewuhic 1y ago
[flagged]
- mort96 1y ago
  I disagree. It's a perfectly fine approach to many kinds of APIs, and people aren't "mediocre" just for using widely accepted words to describe this approach to designing HTTP APIs.
  - blueflow 1y ago
    > and people aren't "mediocre" just for using widely accepted words If you work off "widely accepted words" when there is disagreeing primary literature, you are probably mediocre.
    - mort96 1y ago
      So your view is that the person who coins a term forever has full rights to dictate the meaning of that term, regardless of what meaning turns out to be useful in practice and gets broadly accepted by the community? And you think that anyone who disagrees with such an ultra-prescriptivist view of linguistics is somehow a "mediocre programmer"? Do I have that right?
      - blueflow 1y ago
        No. For all people who use "REST": If reading Fielding is the exception that gets you on HN, than not reading Fielding is what average person does. Mediocre. Using Fieldings term to refer to something else is an extra source of confusion which kinda makes the term useless. Nobody knows what the speaker exactly refers no.
      - homebrewer 1y ago
        I have no dog in this fight, but 90% of technical people around me keep calling authentication authorization no matter how many times I explain the difference to those who even care to listen. It's misused in almost every application developed in this country. Sometimes it really is bad and "everybody" can be very wrong, yes. None of us are native English speakers (most don't speak English at all), so these foreign sounding words all look the same, it's a forgivable "offence".
  - ewuhic 1y ago
    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.
    - mort96 1y ago
      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 the appropriate HTTP methods". The term we have for that kind of API is "rest". And that's fine.
      - ewuhic 1y ago
        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.
        motorest 1y ago
        You're being needlessly pedantic, and it seems the only purpose to this pedantry is finding a pretext to accuse everyone of being mediocre.
        mort96 1y ago
        > 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.
- lillecarl 1y ago
  I met a DevOps guy who didn't know what "dotfiles" are. However I'd argue people who use the term to describe it the same as everyone else is the smart one, if you want to refer to the "real" one just add "strict" or "real" in front of it. I don't think we should dismiss people over drifting definitions and lack of "fountational knowledge".
- IceDane 1y ago
  What an incredibly bad take.
- runroader 1y ago
  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-type, how many different representations do I need? JSON is a given anymore, and maybe XML, but why not plain text, why not PDF? My job isn't an academic paper, good enough to get the job done is going to have to be good enough.
  - okr 1y ago
    I agree, thought it would be really really nice if a http method like GET would not modify things. :)
  - thaumasiotes 1y ago
    > 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. Really? What if somebody else wants to get some information to you? How do you know what to work on?
    - runroader 1y ago
      Pretty much everyone speaks English too, it's the official language of the company. Though we all try to be respectful; if I can't understand them then they tell me again in English. I try to respond as much as possible in German and switch to English if needed - there's also heavy use of deepl on my side which seems to be a lot more idiomatic than Google, MS, or Apple translate.
  - eadmund 1y ago
    > This is more like people arguing over "proper" English, the point of language is to communicate ideas. ur s0 rait, eye d0nt nnno wy ne1 b0dderz tu b3 "proppr"!!!!1!! </sarcasm> You are correct that communication is the point. Words do communicate a message. So too does disrespect for propriety: it communicates the message that the person who is ignorant or disrespectful of proper language is either uneducated or immature, and that in turn implies that such a person’s statements and opinions should be discounted if not ignored entirely. Words and terms mean things. The term ‘REST’ was coined to mean something. I contend that the thing ‘REST’ originally denoted is a valuable thing to discuss, and a valuable thing to employ (I could be wrong, but how easy will it be for us to debate that if we can’t even agree on a term for the thing?). It’s similar to the ironic use of the word ‘literally.’ The word has a useful meaning, there is already the word ‘figuratively’ which can be used to mean ‘not literally’ and a good replacement for the proper meaning of ‘literally’ doesn’t spring to mind: misusing it just decreases clarity and hinders communication. > If my API is supposed to rely on content-type, how many different representations do I need? JSON is a given anymore, and maybe XML, but why not plain text, why not PDF? Whether something is JSON or XML is independent of the representation — they are serialisations (or encodings) of a representation. E.g. {"type": "foo","id":1}, <foo id="1"/>, <foo><id>1</id></foo> and (foo (id 1)) all encode the same representation.
delusional 1y ago
Importantly for the discussion, this also doesn't mean the push for REST api's was a failure. Sure, we didn't end up with what was precisely envisioned from that paper, but we still got a whole lot better than CORBA and SOAP. The lowest common denominator in the REST world is a lot better than the lowest common denominator in SOAP world, but you have to convince the technically literate and ideological bunch first.
- hnfong 1y ago
  We still have gRPC though...
pantulis 1y ago
> The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec I had to chuckle here. So true!
skrebbel 1y ago
Hell yeah. IMO we should collectively get over ourselves and just agree that what you describe is the true, proper, present-day meaning of "REST API".
OJFord 1y ago
> I can safely assume [...] CRUD actions are mapped to POST/GET/PUT/DELETE Not totally sure about that - I think you need to check what they decided about PUT vs PATCH.
- Xenoamorphous 1y ago
  Isn't that fairly straightforward? PUT for full updates and PATCH for partial ones. Does anybody do anything different?
  - blueflow 1y ago
    PUT for partial updates, yes, constantly. What i worked with last week: https://docs.gitlab.com/api/projects/#edit-a-project https://docs.gitlab.com/api/projects/#edit-a-project
  - CSMastermind 1y ago
    Lots of people make PUTs that work like PATCHes and it drives me crazy. Same with people who use POST to retrieve information.
    - akvadrako 1y ago
      Well you can't reliably use GET with bodies. There is the proposed SEARCH but using custom methods also might not work everywhere.
      - Deukhoofd 1y ago
        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.
      - bmn__ 1y ago
        No, QUERY. https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-safe-method-w-body#section-2 https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-saf... SEARCH is from RFC 5323 (WebDAV).
raverbashing 1y ago
Yeah I can assure you very few people care And why would they? They're getting value out of this and it fits their head and model view Sweating over this takes you nowhere
ohdeargodno 1y ago
>- There's a decent chance listing endpoints were changed to POST to support complex filters Please. Everyone knows they tried to make the complex filter work as a GET, then realized the filtering query is so long that it breaks whatever WAF or framework is being used because they block queries longer than 4k chars.
the__alchemist 1y ago
I use the term "HTTP API"; more general. Context, in light of your definition: In many cases labeled "REST", there will only be POST, or POST and GET, and HTTP 200 status with an error in JSON is used instead of HTTP status codes. Your definition makes sense as a weaker form of the original, but it it still too strict compared to how the term is used. "REST" = "HTTP with JSON bodies" is the most practical definition I have.
- Gormo 1y ago
  > HTTP 200 status with an error in JSON is used instead of HTTP status codes I've seen some APIs that not only always return a 200 code, but will include a response in the JSON that itself indicates whether the HTTP request was successfully received, not whether the operation was successfully completed. Building usable error handling with that kind of response is a real pain: there's no single identifier that indicates success/failure status, so we had to build our own lookup table of granular responses specific to each operation.
- VladVladikoff 1y ago
  >HTTP 200 status with an error in JSON is used instead of HTTP status codes This is a bad approach. It prevents your frontend proxies from handling certain errors better. Such as: caching, rate limiting, or throttling abuse.
  - rplnt 1y ago
    On the other hand, functional app returning http errors clouds your observability and can hide real errors. It's not always ideal for the client either. 404 specifically is bad. Do I have a wrong id, wrong address, is it actually 401/403, or is it just returned by something along the way? Code alone tells you nothing, might as well return 200 for a valid request that was correctly processed. (devil's advocate, I use http codes :))
k2xl 1y ago
This is very true. Over my 15 years of engineering, I have never suffered_that_ much with integrating with an api (assuming it exists). So the lack of "HATEOaS" hasn't even been noticable for me. As long as they get most of the 400 status codes right (specifically 200, 401, 403, 429) I usually have no issuss integrating and don't even notice that they don't have some "discoverable api". As long as I can get the data I need or can make the update I need I am fine. I think good rest api design is more a service for the engineer than the client.
- mrweasel 1y ago
  > As long as they get most of the 400 status codes right (specifically 200, 401, 403, 429) A client had build an API that would return 200 on broken requests. We pointed it out and asked if maybe it could return 500, to make monitoring easier. Sure thing, next version "Http 200 - 500", they just wrote 500 in the message body, return remained 200. Some developers just do not understand http.
  - jghn 1y ago
    Ive seen this a few times in the past but for a different reason. What would happen in these cases was that internally there’d be some cascade of calls to microservices that all get collected. In the most egregious examples it’s just some proxy call wrapping the “real” response. So it becomes entirely possible to get a 200 from the thing responding g to you but it may be wrapping an upstream error that gave it a 500.
    - Sharlin 1y ago
      Sometimes I wish HN supported emojis so I could reply with the throw-up one.
  - LinXitoW 1y ago
    I've had frontend devs ask for this, because it was "easier" to handle everything in the same then callback. They wanted me to put ANY error stuff as a payload in the response.
  - 1y ago
eska 1y ago
While I ask people whether they actually mean REST according to the paper or not, I am one of the people who refuse to just move on. The reason being that the mainstream use of the term doesn’t actually mean anything, it is not useful, and therefore not pragmatic at all. I basically say “so you actually just mean some web API, ok” and move on with that. The important difference being that I need to figure out the peculiarities of each such web API.
- osigurdson 1y ago
  >> The important difference being that I need to figure out the peculiarities of each such web API So if they say it is Roy Fielding certified, you would not have to figure out any "peculiarities"? I'd argue that creating a typical OpenAPI style spec which sticks to standard conventions is more professional than creating a pedantically HATEOAS API. Users of your API will be confused and confusion leads to bugs.
  - gfody 1y ago
    op's article could've been plucked from 2012 - this is one of my favorite rest rants from 2012: https://mikehadlow.blogspot.com/2012/08/rest-epic-semantic-fail.html https://mikehadlow.blogspot.com/2012/08/rest-epic-semantic-f... ..that was written before swagger/openAPI was a thing. now there's a real spec with real adoption and real tools and folks can let the whole rest-epic-semantic-fail be an early chapter of web devs doing what they do (like pointing at remotely relevant academic paper to justify what they're doing at work)
- infecto 1y ago
  So you enjoy being pedantic for the sake of being pedantic? I see no useful benefit either from a professional or social setting to act like this. I don’t find this method of discovery very productive and often regardless of meeting some standard in the API the real peculiarities are in the logic of the endpoints and not the surface.
  - hiAndrewQuinn 1y ago
lazyasciiart 1y ago
Haha, our API still returns XML. At least, most of the endpoints do. Not the ones written by that guy who thinks predictability in an API is lower priority than modern code, those ones return JSON.
- anonymars 1y ago
  I present to you this monstrosity: https://stackoverflow.com/q/39110233 https://stackoverflow.com/q/39110233 Presumably they had an existing API, and then REST became all the rage, so they remapped the endpoints and simply converted the XML to JSON. What do you do with the <tag>value</tag> construct? Map it to the name `$`! Congratulations, we're REST now, the world is a better place for it. Off to the pub to celebrate, gents. Ugh. I think people tend to forget these things are tools, not shackles
impostervt 1y ago
As long as it's not SOAP, it's great.
- VladVladikoff 1y ago
  If I never have to use SOAP again in my life, I will die a happy man.
deleted 1y ago
[deleted]
lucideer 1y ago
> - CRUD actions are mapped to POST/GET/PUT/DELETE Agree on your other three but I've seen far too many "REST APIs" with update, delete & even sometimes read operations behind a POST. "SOAP-style REST" I like to call it.
- oneeyedpigeon 1y ago
  > even sometimes read operations behind a POST Even worse than that, when an API like the Pinboard API (v1) uses GET for write operations!
  - appreciatorBus 1y ago
    I work with an API that uses GET for delete :)
- tgv 1y ago
  Do you care? From my point of view, post, put, delete, update, and patch all do the same. I would argue that if there is a difference, making the distinction in the url instead of the request method makes it easier to search code and log. And what's the correct verb anyway? So that's an argument that there may be too many request methods, but you could also argue there aren't enough. But then standardization becomes an absolute mess. So I say: GET or POST.
  - andrehacker 1y ago
    I agree. From what I have seen in corporate settings, using anything more than GET/POST takes the time to deploy the API to a different level. Using UPDATE, PATCH etc. typically involves firewall changes that may take weeks or months to get approved and deployed followed a never ending audit/re-justification process.
  - troupo 1y ago
    > From my point of view, post, put, delete, update, and patch all do the same. That's how we got POST-only GraphQL. In HTTP (and hence REST) these verbs have well-defined behaviour, including the very important things like idempotence and caching: https://github.com/for-GET/know-your-http-well/blob/master/methods.md https://github.com/for-GET/know-your-http-well/blob/master/m...
Cthulhu_ 1y ago
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 just see the response yourself, right?". At least that was the state ~2012, nowadays they use an OpenAPI spec but it's often incomplete, regardless of whether it's handmade (in which case people don't know everything they have to fill in) or generated (in which case the generators will often have limitations and MAYBE support for some custom comments that can fill in the gaps).
- Zambyte 1y ago
  Assuming the / was meant to describe it as both an HTTP API and a JSON API (rather than HTTP API / JSON API) it should be JSON/HTTP, as it is JSON over HTTP, like TCP/IP or GNU/Linux :)
- ivan_gammel 1y ago
  This. Or maybe we should call it "Rest API" in lowercase, meaning not the state transfer, but the state of mind, where developer reached satisfaction with API design and is no longer bothered with hypermedia controls, schemas etc.
- motorest 1y ago
  > HTTP/JSON API works too, but you can assume it's what they mean by REST. This is the kind of slippery slope where pedantic nitpickers thrive. The start to complain that if you accept any media type other than JSON then it's not "REST-adjacent" anymore because JSON is in the name and some bloke wrote down somewhere that JSON was a trait of this architectural style. In this sense, the term "RESTful" is useful to shut down these pedantic nitpickers. It's "REST-adjacent" still, but the right answer to nitpicking is "who cares".
  - troupo 1y ago
    > The start to complain that if you accept any media type other than JSON then it's not "REST-adjacent" anymore because JSON is in the name and some bloke wrote down somewhere that JSON was a trait of this architectural style. wat? Nowhere is JSON in the name of REpresentational State Transfer. Moreover, sending other representations than JSON (and/or different presentations in JSON) is not only acceptable, but is really a part of REST
enobrev 1y ago
Sounds about right. I've been calling this REST-ish for years and generally everyone I say that to gets what I mean without much (any) explanation.
motorest 1y ago
> I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. Why do people feel compelled to even consider it to be a battle? As I see it, the REST concept is useful, but the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves. This is in line with the Richardson maturity model[1], where the apex of REST includes all the HATEOAS bells and whistles. Should REST without HATEOAS classify as REST? Why not? I mean, what is the strong argument to differentiate an architectural style that meets all but one requirement? And is there a point to this nitpicking if HATEOAS is practically irrelevant and the bulk of RESTful APIs do not implement it? What's the value in this nitpicking? Is there any value to cite thesis as if they where Monty Python skits? [1] https://en.wikipedia.org/wiki/Richardson_Maturity_Model https://en.wikipedia.org/wiki/Richardson_Maturity_Model
- naasking 1y ago
  HATEOAS adds lots of practical value if you care about discoverability and longevity.
  - programmarchy 1y ago
    For most APIs that doesn’t deliver any value which can’t be gained from API docs, so it’s hard to justify. However, these days it could be very useful if you want an AI to be able to navigate your API. But MCP has the spotlight now.
    - naasking 1y ago
      And that's fine, but then you're doing RPC instead of REST and we should all be clear and honest about that.
      - Spivak 1y ago
        I think you throw away a useful description of an API by lumping them all under RPC. If you tell me your API is RPC instead of REST then I'll assume that: * If the API is available over HTTP then the only verb used is POST. * The API is exposed on a single URL and the `method` is encoded in the body of the request.
fud101 1y ago
> I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. True. Losing hacking/hacker was sad but I can live with it - crypto becoming associated with scam coins instead of cryptography makes me want to fight.
meehai 1y ago
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?
- shagie 1y ago
  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.
  - koolala 1y ago
    Isn't this twice as slow? If your server was far away it would double load times?
    - ivan_gammel 1y ago
      The response to POST can return everything you need. The Location header that you receive with it will contain permanent link for making the same search request again via GET. Pros: no practical limit on query size. Cons: permalink is not user-friendly - you cannot figure out what filters are applied without making the request.
  - blueflow 1y ago
    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.
    - rswail 1y ago
      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).
nico 1y ago
> Like Agile, CI or DevOps you can insist on the original definition or submit to the semantic diffusion and use the terms as they are commonly understood This is an insightful observation. It happens with pretty much everything As it has been happening recently with the term vibecoding. It started with some definition, and now it’s morphed into more or less just meaning ai-assisted coding. Some people don’t like it[1] 1: https://simonwillison.net/2025/Mar/19/vibe-coding/ https://simonwillison.net/2025/Mar/19/vibe-coding/
marcosdumay 1y ago
I really hate my conclusions here, but from a limited freedom point of view, if all of that is going to happen... > The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec So we should better start with a standard scaffolding for the replies so we can encode the errors and forget about status codes. So the only thing generating an error status is unhandled exception mapped to 500. That's the one design that survives people disagreeing. > There's a decent chance listing endpoints were changed to POST to support complex filters So we'd better just standardize that lists support both GET and POST from the beginning. While you are there, also accept queries on both the url and body parameters.
- bokchoi 1y ago
  The world would be lovely if we could have standard error, listing responses, and a common query syntax. I haven't done REST apis in a while, but I came across this recently for standardizing the error response: https://www.rfc-editor.org/rfc/rfc9457.html https://www.rfc-editor.org/rfc/rfc9457.html
  - marcosdumay 1y ago
    I really like the idea of a type URL.
deleted 1y ago
[deleted]
cratermoon 1y ago
> 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.
bunderbunder 1y ago
I also view it as inevitable. I can count on one hand the number of times I've worked on a service that can accurately be modeled as just representational state transfer. The rest have at least some features that are inherently, inescapably some form of remote procedure call. Which the original REST model eschews. This creates a lot of impedance mismatch, because the HTTP protocol's semantics just weren't designed to model that kind of thing. So yeah, it is hard to figure out how to shoehorn that into POST/GET/PUT/DELETE and HTTP status codes. And folks who say it's easy tend to get there by hyper-focusing on that one time they were lucky enough to be working on a project where it wasn't so hard, and dismissing as rare exceptions the 80% of cases where it did turn out to be a difficult quagmire that forced a bunch of unsatisfying compromises. Alternatively you can pick a protocol that explicitly supports RPC. But that's not necessarily any better because all the well-known options with good language support are over-engineered monstrosities like GRPC, SOAP, and (shudder) CORBA. It might reduce your domain modeling headaches, but at the cost of increased engineering and operations hassle. I really can't blame anyone for deciding that an ad-hoc, ill-specified, janky application of not-actually-REST is the more pragmatic option. Because, frankly, it probably is.
- SoftTalker 1y ago
  xml-rpc (before it transmogrified into SOAP) was pretty simple and flexible. Still exists, and there is a JSON variant now too. It's effectively what a lot of web APIs are: a way to invoke a method or function remotely.
deleted 1y ago
[deleted]
PaulHoule 1y ago
Fielding won the war precisely because he was intellectually incoherent and mostly wrong. It's the "worse is better" of the 21st century. RPC systems were notoriously unergonomic and at best marginally successful. See Sun RPC, RMI, DCOM, CORBA, XML-RPC, SOAP, Protocol Buffers, etc. People say it is not RPC but all the time we write some function in Javascript like const getItem = async (itemId) => { ... } which does a GET /item/{item_id} and on the backend we have a function that looks like Item getItem(String itemId) { ... } with some annotation that explains how to map the URL to an item call. So it is RPC, but instead of a highly complex system that is intellectually coherent but awkward and makes developers puke, we have a system that's more manual than it could be but has a lot of slack and leaves developers feeling like they're in control. 80% of what's wrong with it is that people won't just use ISO 8601 dates.
- majkinetor 1y ago
  Amen. Particularly ISO8601.
  - yndoendo 1y ago
    Always thought that a standard like ISO8601 which always stores the date and time in UTC but appends the local time zone would beneficial.
    - theamk 1y ago
      I don't think I ever needed something like that... Since most cases don't need local time zone, why not keep two separate fields?
      - Jenk 1y ago
        It's a delimited string. There are many fields within that string already. "2025-07-10T09:48:27+01:00" That contains, by my quick glance, at least 8 fields of information. I would argue the one field it does not carry but probably should is the _name_ of the timezone it is for.
yieldcrv 1y ago
100% agreed, “language evolves” This article also tries to make the distinction of not focusing on the verbs themselves. That the RESTful dissertation doesn’t focus on them. The other side of this is that the IETF RESTful proposals from 1999 that talk about the protocol for implementation are just incomplete. The obscure verbs have no consensus on their implementation and libraries across platforms may do PUT, PATCH, DELETE incompatibly. This is enough reason to just stick with GET and POST and not try to be a strict REST adherents since you’ll hit a wall.
necovek 1y ago
To me, the most important nuance really is that just like "hypermedia links" (encoded as different link types, either with Link HTTP header or within the returned results) are "generic" (think that "activate" link), so is REST as done today: if you messed up and the proper action should not be "activate" but "enable", you are in no better position than having to change from /api/v1/account/ID/activate to /api/v2/account/ID/enable. You still have to "hard code" somewhere what action anything needs to do over an API (and there is more missing metadata, like icons, translations for action description...). Mostly to say that any thought of this approach being more general is only marginal, and really an illusion!
agumonkey 1y ago
this is most probably a 90% hit
foobarian 1y ago
I've been doing web development for more than a decade and I still can't figure out what REST actually means, it's more of a vibe. When I think about some of the RESTy things we do like return part of the response as different HTTP codes, they don't really add that much value vs. keeping things on the same layer. So maybe the biggest value add so far is JSON, which thanks to its limited nature prevents complication, and OpenAPI ecosystem which grew kinda organically to provide pretty nice codegen and clients. More complexity lessons here: look at oneOf support in OpenAPI implementations, and you will find half of them flat out don't have it, and the other half are buggy even in YOTL 2025.
- 9dev 1y ago
  > I've been doing web development for more than a decade and I still can't figure out what REST actually means, it's more of a vibe. While I generally agree that REST isn’t really useful outside of academic thought experiments: I’ve been in this about as long as you are, and it really isn’t hard. Try reading Fieldings paper once; the ideas are sound and easy to understand, it’s just with a different vision of the internet than the one we ended up creating.
  - masklinn 1y ago
    You can also read Fielding’s old blog posts. He used to write about it a lot before before he stopped blogging.
turnsout 1y ago
> The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec Haha yes! Is it even a dev team if they haven't had an overly heated argument about which 4xx code to return for an error state?
Waterluvian 1y ago
I describe mine as a JSON-Based Representational State SOAP API to other internal teams. When their eyes cross I get to work sifting through the contents of their pockets for linting errors and JIRA tickets.
synergy20 1y ago
RESTful has gone far beyond the http world. It's the new RPC with JSON payload for whatever. I use it on embedded systems that has no database at all, POST/GET/PUT/DELETE etc are perfectly simple to map into WRITE|READ|Modify|Remove commands. As long as the API is documented, I don't really care about its http origins.
esafak 1y ago
> The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec 401 Unauthorized. When the user is unauthenticated. 403 Forbidden. When the user is unauthorized.
Joker_vD 1y ago
> - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec I really wish people just used 200 status code and put encoded errors in the payloads themselves instead of trying to fuse the transport layer's (which HTTP serves as, in this case) concerns with the application's concerns. Seriously, HTTP does not mandate that e.g. "HTTP/1.1 503 Ooops\r\n\r\n" should be stuffed into the TCP's RST packet, or into whatever TLS uses to signal severe errors, for bloody obvious reasons: it doesn't belong there. Like, when you get a 403/404 error, it's very bloody difficult to tell apart the "the reverse proxy before the server is misconfigured and somebody forgot to expose the endpoint" and "the server executed your request to look up an item perfectly fine: the DB is functional, and the item you asked for is not in there" scenarios. And yeah, of course I could (and should) look at and try to parse the response's body but why? This "let's split off the 'error code' part of the message from the message and stuff it somewhere into the metadata, that'll be fine, those never get messed up or used for anything else, so no chance of confusion" approach just complicates things for everyone for no benefit whatsoever.
- TOGoS 1y ago
  Eh, if you're doing RPC where the whole request/response are already in another layer on top of HTTP, then sure, 200 everything. But to me, "REST" means "use the HTTP verbs to talk about resources". The whole point is that for resource-oriented APIs, you don't need another layer. In which case serving 404s for things that don't exist, or 409s when you try to put things into a weird state makes perfect sense.
- potamic 1y ago
  The point of status codes is to have a standard that any client can understand. If you have a load balancer, the load balancer can unhealthy backends based on the status code. Similarly if you have some job scheduler or workflow engine that's calling your API, they can execute an appropriate retry strategy based on the status code. The client in most cases does not care about why something failed, only whether it has failed. Being able to tell apart if the failure was due to reverse proxy or database or whatever is the server's concern and the server can always do that with its own custom error codes.
drewcoo 1y ago
I have seen monstrosities claiming to be rest that use HTTP but actually have a separate set of action verbs, nestled inside of HTTP's. In a server holding a "deck of cards," there might be a "HTTP GET <blah-de-blah>/shuffle.html" call with the side-effect of performing a server-side randomization operation. I just made that up because I don't want to impugn anyone. But I've seen API sets full of nonsense just like that.
gherkinnn 1y ago
Exactly. What you describe is how I see REST being used today and I wish people accepted the semantic shift and stopped with their well-ackshually. It serves nothing.
pbreit 1y ago
- the inclusion of HATEAOS links which are NEVER used

ewuhic 1y ago

[flagged]

mort96 1y ago
I disagree. It's a perfectly fine approach to many kinds of APIs, and people aren't "mediocre" just for using widely accepted words to describe this approach to designing HTTP APIs.
- blueflow 1y ago
  > and people aren't "mediocre" just for using widely accepted words If you work off "widely accepted words" when there is disagreeing primary literature, you are probably mediocre.
  - mort96 1y ago
    So your view is that the person who coins a term forever has full rights to dictate the meaning of that term, regardless of what meaning turns out to be useful in practice and gets broadly accepted by the community? And you think that anyone who disagrees with such an ultra-prescriptivist view of linguistics is somehow a "mediocre programmer"? Do I have that right?
    - blueflow 1y ago
      No. For all people who use "REST": If reading Fielding is the exception that gets you on HN, than not reading Fielding is what average person does. Mediocre. Using Fieldings term to refer to something else is an extra source of confusion which kinda makes the term useless. Nobody knows what the speaker exactly refers no.
    - homebrewer 1y ago
      I have no dog in this fight, but 90% of technical people around me keep calling authentication authorization no matter how many times I explain the difference to those who even care to listen. It's misused in almost every application developed in this country. Sometimes it really is bad and "everybody" can be very wrong, yes. None of us are native English speakers (most don't speak English at all), so these foreign sounding words all look the same, it's a forgivable "offence".
- ewuhic 1y ago
  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.
  - mort96 1y ago
    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 the appropriate HTTP methods". The term we have for that kind of API is "rest". And that's fine.
    - ewuhic 1y ago
      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.
      - motorest 1y ago
        You're being needlessly pedantic, and it seems the only purpose to this pedantry is finding a pretext to accuse everyone of being mediocre.
      - mort96 1y ago
        > 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.
lillecarl 1y ago
I met a DevOps guy who didn't know what "dotfiles" are. However I'd argue people who use the term to describe it the same as everyone else is the smart one, if you want to refer to the "real" one just add "strict" or "real" in front of it. I don't think we should dismiss people over drifting definitions and lack of "fountational knowledge".
IceDane 1y ago
What an incredibly bad take.
runroader 1y ago
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-type, how many different representations do I need? JSON is a given anymore, and maybe XML, but why not plain text, why not PDF? My job isn't an academic paper, good enough to get the job done is going to have to be good enough.
- okr 1y ago
  I agree, thought it would be really really nice if a http method like GET would not modify things. :)
- thaumasiotes 1y ago
  > 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. Really? What if somebody else wants to get some information to you? How do you know what to work on?
  - runroader 1y ago
    Pretty much everyone speaks English too, it's the official language of the company. Though we all try to be respectful; if I can't understand them then they tell me again in English. I try to respond as much as possible in German and switch to English if needed - there's also heavy use of deepl on my side which seems to be a lot more idiomatic than Google, MS, or Apple translate.
- eadmund 1y ago
  > This is more like people arguing over "proper" English, the point of language is to communicate ideas. ur s0 rait, eye d0nt nnno wy ne1 b0dderz tu b3 "proppr"!!!!1!! </sarcasm> You are correct that communication is the point. Words do communicate a message. So too does disrespect for propriety: it communicates the message that the person who is ignorant or disrespectful of proper language is either uneducated or immature, and that in turn implies that such a person’s statements and opinions should be discounted if not ignored entirely. Words and terms mean things. The term ‘REST’ was coined to mean something. I contend that the thing ‘REST’ originally denoted is a valuable thing to discuss, and a valuable thing to employ (I could be wrong, but how easy will it be for us to debate that if we can’t even agree on a term for the thing?). It’s similar to the ironic use of the word ‘literally.’ The word has a useful meaning, there is already the word ‘figuratively’ which can be used to mean ‘not literally’ and a good replacement for the proper meaning of ‘literally’ doesn’t spring to mind: misusing it just decreases clarity and hinders communication. > If my API is supposed to rely on content-type, how many different representations do I need? JSON is a given anymore, and maybe XML, but why not plain text, why not PDF? Whether something is JSON or XML is independent of the representation — they are serialisations (or encodings) of a representation. E.g. {"type": "foo","id":1}, <foo id="1"/>, <foo><id>1</id></foo> and (foo (id 1)) all encode the same representation.

delusional 1y ago

Importantly for the discussion, this also doesn't mean the push for REST api's was a failure. Sure, we didn't end up with what was precisely envisioned from that paper, but we still got a whole lot better than CORBA and SOAP. The lowest common denominator in the REST world is a lot better than the lowest common denominator in SOAP world, but you have to convince the technically literate and ideological bunch first.

hnfong 1y ago
We still have gRPC though...

pantulis 1y ago

> The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec I had to chuckle here. So true!

skrebbel 1y ago

Hell yeah. IMO we should collectively get over ourselves and just agree that what you describe is the true, proper, present-day meaning of "REST API".

OJFord 1y ago

> I can safely assume [...] CRUD actions are mapped to POST/GET/PUT/DELETE Not totally sure about that - I think you need to check what they decided about PUT vs PATCH.

Xenoamorphous 1y ago
Isn't that fairly straightforward? PUT for full updates and PATCH for partial ones. Does anybody do anything different?
- blueflow 1y ago
  PUT for partial updates, yes, constantly. What i worked with last week: https://docs.gitlab.com/api/projects/#edit-a-project https://docs.gitlab.com/api/projects/#edit-a-project
- CSMastermind 1y ago
  Lots of people make PUTs that work like PATCHes and it drives me crazy. Same with people who use POST to retrieve information.
  - akvadrako 1y ago
    Well you can't reliably use GET with bodies. There is the proposed SEARCH but using custom methods also might not work everywhere.
    - Deukhoofd 1y ago
      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.
    - bmn__ 1y ago
      No, QUERY. https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-safe-method-w-body#section-2 https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-saf... SEARCH is from RFC 5323 (WebDAV).

raverbashing 1y ago

Yeah I can assure you very few people care And why would they? They're getting value out of this and it fits their head and model view Sweating over this takes you nowhere

ohdeargodno 1y ago

>- There's a decent chance listing endpoints were changed to POST to support complex filters Please. Everyone knows they tried to make the complex filter work as a GET, then realized the filtering query is so long that it breaks whatever WAF or framework is being used because they block queries longer than 4k chars.

the__alchemist 1y ago

I use the term "HTTP API"; more general. Context, in light of your definition: In many cases labeled "REST", there will only be POST, or POST and GET, and HTTP 200 status with an error in JSON is used instead of HTTP status codes. Your definition makes sense as a weaker form of the original, but it it still too strict compared to how the term is used. "REST" = "HTTP with JSON bodies" is the most practical definition I have.

Gormo 1y ago
> HTTP 200 status with an error in JSON is used instead of HTTP status codes I've seen some APIs that not only always return a 200 code, but will include a response in the JSON that itself indicates whether the HTTP request was successfully received, not whether the operation was successfully completed. Building usable error handling with that kind of response is a real pain: there's no single identifier that indicates success/failure status, so we had to build our own lookup table of granular responses specific to each operation.
VladVladikoff 1y ago
>HTTP 200 status with an error in JSON is used instead of HTTP status codes This is a bad approach. It prevents your frontend proxies from handling certain errors better. Such as: caching, rate limiting, or throttling abuse.
- rplnt 1y ago
  On the other hand, functional app returning http errors clouds your observability and can hide real errors. It's not always ideal for the client either. 404 specifically is bad. Do I have a wrong id, wrong address, is it actually 401/403, or is it just returned by something along the way? Code alone tells you nothing, might as well return 200 for a valid request that was correctly processed. (devil's advocate, I use http codes :))

k2xl 1y ago

This is very true. Over my 15 years of engineering, I have never suffered_that_ much with integrating with an api (assuming it exists). So the lack of "HATEOaS" hasn't even been noticable for me. As long as they get most of the 400 status codes right (specifically 200, 401, 403, 429) I usually have no issuss integrating and don't even notice that they don't have some "discoverable api". As long as I can get the data I need or can make the update I need I am fine. I think good rest api design is more a service for the engineer than the client.

mrweasel 1y ago
> As long as they get most of the 400 status codes right (specifically 200, 401, 403, 429) A client had build an API that would return 200 on broken requests. We pointed it out and asked if maybe it could return 500, to make monitoring easier. Sure thing, next version "Http 200 - 500", they just wrote 500 in the message body, return remained 200. Some developers just do not understand http.
- jghn 1y ago
  Ive seen this a few times in the past but for a different reason. What would happen in these cases was that internally there’d be some cascade of calls to microservices that all get collected. In the most egregious examples it’s just some proxy call wrapping the “real” response. So it becomes entirely possible to get a 200 from the thing responding g to you but it may be wrapping an upstream error that gave it a 500.
  - Sharlin 1y ago
    Sometimes I wish HN supported emojis so I could reply with the throw-up one.
- LinXitoW 1y ago
  I've had frontend devs ask for this, because it was "easier" to handle everything in the same then callback. They wanted me to put ANY error stuff as a payload in the response.
- 1y ago

eska 1y ago

While I ask people whether they actually mean REST according to the paper or not, I am one of the people who refuse to just move on. The reason being that the mainstream use of the term doesn’t actually mean anything, it is not useful, and therefore not pragmatic at all. I basically say “so you actually just mean some web API, ok” and move on with that. The important difference being that I need to figure out the peculiarities of each such web API.

osigurdson 1y ago
>> The important difference being that I need to figure out the peculiarities of each such web API So if they say it is Roy Fielding certified, you would not have to figure out any "peculiarities"? I'd argue that creating a typical OpenAPI style spec which sticks to standard conventions is more professional than creating a pedantically HATEOAS API. Users of your API will be confused and confusion leads to bugs.
- gfody 1y ago
  op's article could've been plucked from 2012 - this is one of my favorite rest rants from 2012: https://mikehadlow.blogspot.com/2012/08/rest-epic-semantic-fail.html https://mikehadlow.blogspot.com/2012/08/rest-epic-semantic-f... ..that was written before swagger/openAPI was a thing. now there's a real spec with real adoption and real tools and folks can let the whole rest-epic-semantic-fail be an early chapter of web devs doing what they do (like pointing at remotely relevant academic paper to justify what they're doing at work)
infecto 1y ago
So you enjoy being pedantic for the sake of being pedantic? I see no useful benefit either from a professional or social setting to act like this. I don’t find this method of discovery very productive and often regardless of meeting some standard in the API the real peculiarities are in the logic of the endpoints and not the surface.
- hiAndrewQuinn 1y ago

lazyasciiart 1y ago

Haha, our API still returns XML. At least, most of the endpoints do. Not the ones written by that guy who thinks predictability in an API is lower priority than modern code, those ones return JSON.

anonymars 1y ago
I present to you this monstrosity: https://stackoverflow.com/q/39110233 https://stackoverflow.com/q/39110233 Presumably they had an existing API, and then REST became all the rage, so they remapped the endpoints and simply converted the XML to JSON. What do you do with the <tag>value</tag> construct? Map it to the name `$`! Congratulations, we're REST now, the world is a better place for it. Off to the pub to celebrate, gents. Ugh. I think people tend to forget these things are tools, not shackles

impostervt 1y ago

As long as it's not SOAP, it's great.

VladVladikoff 1y ago
If I never have to use SOAP again in my life, I will die a happy man.

deleted 1y ago

[deleted]

lucideer 1y ago

> - CRUD actions are mapped to POST/GET/PUT/DELETE Agree on your other three but I've seen far too many "REST APIs" with update, delete & even sometimes read operations behind a POST. "SOAP-style REST" I like to call it.

oneeyedpigeon 1y ago
> even sometimes read operations behind a POST Even worse than that, when an API like the Pinboard API (v1) uses GET for write operations!
- appreciatorBus 1y ago
  I work with an API that uses GET for delete :)
tgv 1y ago
Do you care? From my point of view, post, put, delete, update, and patch all do the same. I would argue that if there is a difference, making the distinction in the url instead of the request method makes it easier to search code and log. And what's the correct verb anyway? So that's an argument that there may be too many request methods, but you could also argue there aren't enough. But then standardization becomes an absolute mess. So I say: GET or POST.
- andrehacker 1y ago
  I agree. From what I have seen in corporate settings, using anything more than GET/POST takes the time to deploy the API to a different level. Using UPDATE, PATCH etc. typically involves firewall changes that may take weeks or months to get approved and deployed followed a never ending audit/re-justification process.
- troupo 1y ago
  > From my point of view, post, put, delete, update, and patch all do the same. That's how we got POST-only GraphQL. In HTTP (and hence REST) these verbs have well-defined behaviour, including the very important things like idempotence and caching: https://github.com/for-GET/know-your-http-well/blob/master/methods.md https://github.com/for-GET/know-your-http-well/blob/master/m...

Cthulhu_ 1y ago

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 just see the response yourself, right?". At least that was the state ~2012, nowadays they use an OpenAPI spec but it's often incomplete, regardless of whether it's handmade (in which case people don't know everything they have to fill in) or generated (in which case the generators will often have limitations and MAYBE support for some custom comments that can fill in the gaps).

Zambyte 1y ago
Assuming the / was meant to describe it as both an HTTP API and a JSON API (rather than HTTP API / JSON API) it should be JSON/HTTP, as it is JSON over HTTP, like TCP/IP or GNU/Linux :)
ivan_gammel 1y ago
This. Or maybe we should call it "Rest API" in lowercase, meaning not the state transfer, but the state of mind, where developer reached satisfaction with API design and is no longer bothered with hypermedia controls, schemas etc.
motorest 1y ago
> HTTP/JSON API works too, but you can assume it's what they mean by REST. This is the kind of slippery slope where pedantic nitpickers thrive. The start to complain that if you accept any media type other than JSON then it's not "REST-adjacent" anymore because JSON is in the name and some bloke wrote down somewhere that JSON was a trait of this architectural style. In this sense, the term "RESTful" is useful to shut down these pedantic nitpickers. It's "REST-adjacent" still, but the right answer to nitpicking is "who cares".
- troupo 1y ago
  > The start to complain that if you accept any media type other than JSON then it's not "REST-adjacent" anymore because JSON is in the name and some bloke wrote down somewhere that JSON was a trait of this architectural style. wat? Nowhere is JSON in the name of REpresentational State Transfer. Moreover, sending other representations than JSON (and/or different presentations in JSON) is not only acceptable, but is really a part of REST

enobrev 1y ago

Sounds about right. I've been calling this REST-ish for years and generally everyone I say that to gets what I mean without much (any) explanation.

motorest 1y ago

> I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. Why do people feel compelled to even consider it to be a battle? As I see it, the REST concept is useful, but the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves. This is in line with the Richardson maturity model[1], where the apex of REST includes all the HATEOAS bells and whistles. Should REST without HATEOAS classify as REST? Why not? I mean, what is the strong argument to differentiate an architectural style that meets all but one requirement? And is there a point to this nitpicking if HATEOAS is practically irrelevant and the bulk of RESTful APIs do not implement it? What's the value in this nitpicking? Is there any value to cite thesis as if they where Monty Python skits? [1] https://en.wikipedia.org/wiki/Richardson_Maturity_Model https://en.wikipedia.org/wiki/Richardson_Maturity_Model

naasking 1y ago
HATEOAS adds lots of practical value if you care about discoverability and longevity.
- programmarchy 1y ago
  For most APIs that doesn’t deliver any value which can’t be gained from API docs, so it’s hard to justify. However, these days it could be very useful if you want an AI to be able to navigate your API. But MCP has the spotlight now.
  - naasking 1y ago
    And that's fine, but then you're doing RPC instead of REST and we should all be clear and honest about that.
    - Spivak 1y ago
      I think you throw away a useful description of an API by lumping them all under RPC. If you tell me your API is RPC instead of REST then I'll assume that: * If the API is available over HTTP then the only verb used is POST. * The API is exposed on a single URL and the `method` is encoded in the body of the request.

fud101 1y ago

> I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. True. Losing hacking/hacker was sad but I can live with it - crypto becoming associated with scam coins instead of cryptography makes me want to fight.

meehai 1y ago

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?

shagie 1y ago
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.
- koolala 1y ago
  Isn't this twice as slow? If your server was far away it would double load times?
  - ivan_gammel 1y ago
    The response to POST can return everything you need. The Location header that you receive with it will contain permanent link for making the same search request again via GET. Pros: no practical limit on query size. Cons: permalink is not user-friendly - you cannot figure out what filters are applied without making the request.
- blueflow 1y ago
  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.
  - rswail 1y ago
    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).

nico 1y ago

> Like Agile, CI or DevOps you can insist on the original definition or submit to the semantic diffusion and use the terms as they are commonly understood This is an insightful observation. It happens with pretty much everything As it has been happening recently with the term vibecoding. It started with some definition, and now it’s morphed into more or less just meaning ai-assisted coding. Some people don’t like it[1] 1: https://simonwillison.net/2025/Mar/19/vibe-coding/ https://simonwillison.net/2025/Mar/19/vibe-coding/

marcosdumay 1y ago

I really hate my conclusions here, but from a limited freedom point of view, if all of that is going to happen... > The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec So we should better start with a standard scaffolding for the replies so we can encode the errors and forget about status codes. So the only thing generating an error status is unhandled exception mapped to 500. That's the one design that survives people disagreeing. > There's a decent chance listing endpoints were changed to POST to support complex filters So we'd better just standardize that lists support both GET and POST from the beginning. While you are there, also accept queries on both the url and body parameters.

bokchoi 1y ago
The world would be lovely if we could have standard error, listing responses, and a common query syntax. I haven't done REST apis in a while, but I came across this recently for standardizing the error response: https://www.rfc-editor.org/rfc/rfc9457.html https://www.rfc-editor.org/rfc/rfc9457.html
- marcosdumay 1y ago
  I really like the idea of a type URL.

deleted 1y ago

[deleted]

cratermoon 1y ago

> 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.

bunderbunder 1y ago

I also view it as inevitable. I can count on one hand the number of times I've worked on a service that can accurately be modeled as just representational state transfer. The rest have at least some features that are inherently, inescapably some form of remote procedure call. Which the original REST model eschews. This creates a lot of impedance mismatch, because the HTTP protocol's semantics just weren't designed to model that kind of thing. So yeah, it is hard to figure out how to shoehorn that into POST/GET/PUT/DELETE and HTTP status codes. And folks who say it's easy tend to get there by hyper-focusing on that one time they were lucky enough to be working on a project where it wasn't so hard, and dismissing as rare exceptions the 80% of cases where it did turn out to be a difficult quagmire that forced a bunch of unsatisfying compromises. Alternatively you can pick a protocol that explicitly supports RPC. But that's not necessarily any better because all the well-known options with good language support are over-engineered monstrosities like GRPC, SOAP, and (shudder) CORBA. It might reduce your domain modeling headaches, but at the cost of increased engineering and operations hassle. I really can't blame anyone for deciding that an ad-hoc, ill-specified, janky application of not-actually-REST is the more pragmatic option. Because, frankly, it probably is.

SoftTalker 1y ago
xml-rpc (before it transmogrified into SOAP) was pretty simple and flexible. Still exists, and there is a JSON variant now too. It's effectively what a lot of web APIs are: a way to invoke a method or function remotely.

deleted 1y ago

[deleted]

PaulHoule 1y ago

Fielding won the war precisely because he was intellectually incoherent and mostly wrong. It's the "worse is better" of the 21st century. RPC systems were notoriously unergonomic and at best marginally successful. See Sun RPC, RMI, DCOM, CORBA, XML-RPC, SOAP, Protocol Buffers, etc. People say it is not RPC but all the time we write some function in Javascript like const getItem = async (itemId) => { ... } which does a GET /item/{item_id} and on the backend we have a function that looks like Item getItem(String itemId) { ... } with some annotation that explains how to map the URL to an item call. So it is RPC, but instead of a highly complex system that is intellectually coherent but awkward and makes developers puke, we have a system that's more manual than it could be but has a lot of slack and leaves developers feeling like they're in control. 80% of what's wrong with it is that people won't just use ISO 8601 dates.

majkinetor 1y ago
Amen. Particularly ISO8601.
- yndoendo 1y ago
  Always thought that a standard like ISO8601 which always stores the date and time in UTC but appends the local time zone would beneficial.
  - theamk 1y ago
    I don't think I ever needed something like that... Since most cases don't need local time zone, why not keep two separate fields?
    - Jenk 1y ago
      It's a delimited string. There are many fields within that string already. "2025-07-10T09:48:27+01:00" That contains, by my quick glance, at least 8 fields of information. I would argue the one field it does not carry but probably should is the _name_ of the timezone it is for.

yieldcrv 1y ago

100% agreed, “language evolves” This article also tries to make the distinction of not focusing on the verbs themselves. That the RESTful dissertation doesn’t focus on them. The other side of this is that the IETF RESTful proposals from 1999 that talk about the protocol for implementation are just incomplete. The obscure verbs have no consensus on their implementation and libraries across platforms may do PUT, PATCH, DELETE incompatibly. This is enough reason to just stick with GET and POST and not try to be a strict REST adherents since you’ll hit a wall.

necovek 1y ago

To me, the most important nuance really is that just like "hypermedia links" (encoded as different link types, either with Link HTTP header or within the returned results) are "generic" (think that "activate" link), so is REST as done today: if you messed up and the proper action should not be "activate" but "enable", you are in no better position than having to change from /api/v1/account/ID/activate to /api/v2/account/ID/enable. You still have to "hard code" somewhere what action anything needs to do over an API (and there is more missing metadata, like icons, translations for action description...). Mostly to say that any thought of this approach being more general is only marginal, and really an illusion!

agumonkey 1y ago

this is most probably a 90% hit

foobarian 1y ago

I've been doing web development for more than a decade and I still can't figure out what REST actually means, it's more of a vibe. When I think about some of the RESTy things we do like return part of the response as different HTTP codes, they don't really add that much value vs. keeping things on the same layer. So maybe the biggest value add so far is JSON, which thanks to its limited nature prevents complication, and OpenAPI ecosystem which grew kinda organically to provide pretty nice codegen and clients. More complexity lessons here: look at oneOf support in OpenAPI implementations, and you will find half of them flat out don't have it, and the other half are buggy even in YOTL 2025.

9dev 1y ago
> I've been doing web development for more than a decade and I still can't figure out what REST actually means, it's more of a vibe. While I generally agree that REST isn’t really useful outside of academic thought experiments: I’ve been in this about as long as you are, and it really isn’t hard. Try reading Fieldings paper once; the ideas are sound and easy to understand, it’s just with a different vision of the internet than the one we ended up creating.
- masklinn 1y ago
  You can also read Fielding’s old blog posts. He used to write about it a lot before before he stopped blogging.

turnsout 1y ago

> The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec Haha yes! Is it even a dev team if they haven't had an overly heated argument about which 4xx code to return for an error state?

Waterluvian 1y ago

I describe mine as a JSON-Based Representational State SOAP API to other internal teams. When their eyes cross I get to work sifting through the contents of their pockets for linting errors and JIRA tickets.

synergy20 1y ago

RESTful has gone far beyond the http world. It's the new RPC with JSON payload for whatever. I use it on embedded systems that has no database at all, POST/GET/PUT/DELETE etc are perfectly simple to map into WRITE|READ|Modify|Remove commands. As long as the API is documented, I don't really care about its http origins.

esafak 1y ago

> The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec 401 Unauthorized. When the user is unauthenticated. 403 Forbidden. When the user is unauthorized.

Joker_vD 1y ago

> - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec I really wish people just used 200 status code and put encoded errors in the payloads themselves instead of trying to fuse the transport layer's (which HTTP serves as, in this case) concerns with the application's concerns. Seriously, HTTP does not mandate that e.g. "HTTP/1.1 503 Ooops\r\n\r\n" should be stuffed into the TCP's RST packet, or into whatever TLS uses to signal severe errors, for bloody obvious reasons: it doesn't belong there. Like, when you get a 403/404 error, it's very bloody difficult to tell apart the "the reverse proxy before the server is misconfigured and somebody forgot to expose the endpoint" and "the server executed your request to look up an item perfectly fine: the DB is functional, and the item you asked for is not in there" scenarios. And yeah, of course I could (and should) look at and try to parse the response's body but why? This "let's split off the 'error code' part of the message from the message and stuff it somewhere into the metadata, that'll be fine, those never get messed up or used for anything else, so no chance of confusion" approach just complicates things for everyone for no benefit whatsoever.

TOGoS 1y ago
Eh, if you're doing RPC where the whole request/response are already in another layer on top of HTTP, then sure, 200 everything. But to me, "REST" means "use the HTTP verbs to talk about resources". The whole point is that for resource-oriented APIs, you don't need another layer. In which case serving 404s for things that don't exist, or 409s when you try to put things into a weird state makes perfect sense.
potamic 1y ago
The point of status codes is to have a standard that any client can understand. If you have a load balancer, the load balancer can unhealthy backends based on the status code. Similarly if you have some job scheduler or workflow engine that's calling your API, they can execute an appropriate retry strategy based on the status code. The client in most cases does not care about why something failed, only whether it has failed. Being able to tell apart if the failure was due to reverse proxy or database or whatever is the server's concern and the server can always do that with its own custom error codes.

drewcoo 1y ago

I have seen monstrosities claiming to be rest that use HTTP but actually have a separate set of action verbs, nestled inside of HTTP's. In a server holding a "deck of cards," there might be a "HTTP GET <blah-de-blah>/shuffle.html" call with the side-effect of performing a server-side randomization operation. I just made that up because I don't want to impugn anyone. But I've seen API sets full of nonsense just like that.

gherkinnn 1y ago

Exactly. What you describe is how I see REST being used today and I wish people accepted the semantic shift and stopped with their well-ackshually. It serves nothing.

pbreit 1y ago

- the inclusion of HATEAOS links which are NEVER used