5 ms·

The short answer is... the web moved in a different way than expected and the useful portions of rest were preserved while other portions were jettisoned (the b

by munk-a 4y ago

The short answer is... the web moved in a different way than expected and the useful portions of rest were preserved while other portions were jettisoned (the biggest one IMO isn't the hypertext portion (JSONs fine, it's fine) but the self-discoverable portion - I haven't seen a self-discoverable REST API ever in the wild). Unfortunately the name REST was too awesome sounding and short - so we've never had a fork with a different name that has proclaimed itself as something more accurate. I don't think this is awful, FYI - it's sort of the evolution of tech... the OG REST wouldn't have ever gotten popular due to how stringent it was and I can use "That it's RESTful enough." to reject bad code practices without anyone being able to call me out on it because nobody actually remembers what REST was supposed to be. I'd also add - what precisely is self-descriptive HTML? All descriptions need reference points and nothing will be universally comprehensible - let alone to a machine... expecting a machine to understand what "Insert tendies for stonks." on an endpoint is unreasonable.

masklinn 4y ago
> the useful portions of rest were preserved while other portions were jettisoned Not even remotely. All portions of rest were jettisoned, and the nice branding got slapped on familiar rpc. Fielding’s rest was never about http-specific concepts, not the verbs, not the status code, and not cute-looking URLs.
- kareemsabri 4y ago
  I don't think that's true, unless I just don't understand REST at all. Most "RESTful APIs" in the wild I encounter / implement are - stateless - cacheable - follow client-server architecture - support resource identification in requests - loosely support resource manipulation through representation (with some caveats) I don't see how it's RPC by any but the most broad interpretation (a function executes at another address space).
  - tannhaeuser 4y ago
    The entire point of Fielding's REST was loose coupling - that you don't hard-code interactions/URLs into clients but rather discover actions/links/interaction from representations dynamically, such that the only thing a client must know a priori is a URL. "REST API" practices are criticized because they follow all the rules and brag about eg HTTP response status code semantics and whatnot, but without following HATEOAS which is the entire point of it all. I can see why teams implement "REST APIs" - to end pointless architectural meta discussions and get stuff done; and there's practical value in that. But, harsh as it sounds, and I'm apologizing in advance if this is offending to anyone, dealing with colleagues who mindlessly follow REST casuistry feels like working with hopeless rote learners, psychopathic pretenders, or unstable personalities projecting naive, irrational, and premature ideas of craftsmanship into our profession to me.
    - kareemsabri 4y ago
      I don't think that was the entire point. But who cares? Loose coupling is of little benefit to the client in a client-server pair that are implemented by the same company (which presumably Fielding wasn't picturing). There are other benefits people get from REST. Semantically understandable APIs, handlers that do one thing, predictable interfaces (this is close to as valuable as discoverable imo). I don't really get your point re: casuistry. The implementation of REST as practiced by the industry is largely pragmatic. The article appears to be arguing for REST purity.
      - masklinn 4y ago
        > I don't think that was the entire point. But who cares? People who like language to have meaning? > which presumably Fielding wasn't picturing Fielding was describing an architectural style. Although there may have been an element of advocacy, at the end of the day whether you used it or not was not his concern. > The implementation of REST as practiced by the industry is largely pragmatic. In the same sense that the implementation of airships in Boeing’s 747 is largely pragmatic, except for the part where Boeing doesn’t misscall their plane an airship. > The article appears to be arguing for REST purity. Much like saying a serval is not a dog is arguing for dog purity, yes.
dylan604 4y ago
>(JSONs fine, it's fine) I read this like you're convincing yourself vs the reader.
jakear 4y ago
GitHub’s REST api is pretty self discoverable fwiw. It kinda sucks honestly - every request yields pages of response with field after field of totally irrelevant links. Totally unparseable without json formatting and collapsing support, so CURL/wget/etc. via the terminal are painful. See for example the example response for getting an issue: https://docs.github.com/en/rest/issues/issues#get-an-issue https://docs.github.com/en/rest/issues/issues#get-an-issue And that even has omitted some fields you’d get back querying manually.
- bmn__ 4y ago
  > GitHub’s REST api is pretty self discoverable fwiw. I had a look at the example response to see whether that is true. I give you that there are hyperlinks existing in resources of media type `application/vnd.github+json`, but there is no uniform interface to discover a link. Fielding would disapprove. It's an indication of bad design that a client must hardcode e.g. `labels_url` instead of having a generic reusable way to access a link that works across a multitude of JSON derived media types.
  - munk-a 4y ago
    Wouldn't any interface to discover links need to be hardcoded? IIRC, REST didn't actually define a unified way to describe where the links existed in the returned document.
    - bmn__ 4y ago
      That's because you're looking at the wrong place, that's not the responsibility of REST: it can't because it's not a specification, but a description of an architectural style. Instead, it's the responsibility of the media type. HTML offers hypermedia controls: hyperlinks are denoted with <a>, <area>, <base>, <link> elements and the "href" attribute; forms are denoted with the <form> element as its "action" attribute. I assume you are familiar with HTML, you can see that this is a very generalised way to find links (or controls in general), it is applicable to all HTML documents. XML has close analogues: XLink and XForms. JSON-done-right offers hypermedia controls: moral equivalent of links <https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-5.1 https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#s...>, moral equivalent of forms <https://rwcbook.github.io/hal-forms/ https://rwcbook.github.io/hal-forms/>. It is easy to reimagine `application/vnd.github+json` in the guise of this media type so that the problem I was describing earlier disappears. If a media type cannot express hypermedia controls or link relations inline (e.g. WebP images), then the HTTP header can be used instead, see RFCs 8288 and 6570.
mdaniel 4y ago
> I haven't seen a self-discoverable REST API ever in the wild I'm super cognizant this entire discussion hinges upon semantics, nuance, etc but the Okta API isn't terrible about that https://developer.okta.com/docs/reference/core-okta-api/#hypermedia https://developer.okta.com/docs/reference/core-okta-api/#hyp... I haven't personally tried `curl https://${yourOktaDomain}/api/v1 https://${yourOktaDomain}/api/v1` to see what the bootstrapping process looks like, but I can attest they do return _links in a bunch of their resource responses, and I believe their own SDK uses them, so they're not just lip service
coffee_beqn 4y ago
> a self-discoverable REST API I’ve been writing web services for over a decade and this just seems like a cute idea that is actually almost never at all useful in the real world.
- kareemsabri 4y ago
  Yep, there's a big gap between what's useful in Ph.D dissertations and what's useful in the business of software.
- kortex 4y ago
  Swagger/OpenApi is probably the closest thing to "true REST" with self-discoverable APIs. Without some sort of common schema of where/how to look for resources, there's no real automated discovery to be had without AGI. Turns out, a lot of places don't even want self-discovery. We shut off our openapi.json in prod because a) security b) we don't want bots messing around c) Hyrum's law, as soon as you expose an API endpoint, folks try to build against it and grumble if it chances/goes away. Wikipedia (along with any true wiki) is, and likely forever will be, the one true REST/HATEOAS application.

by munk-a 4y ago

masklinn 4y ago

> the useful portions of rest were preserved while other portions were jettisoned Not even remotely. All portions of rest were jettisoned, and the nice branding got slapped on familiar rpc. Fielding’s rest was never about http-specific concepts, not the verbs, not the status code, and not cute-looking URLs.

kareemsabri 4y ago
I don't think that's true, unless I just don't understand REST at all. Most "RESTful APIs" in the wild I encounter / implement are - stateless - cacheable - follow client-server architecture - support resource identification in requests - loosely support resource manipulation through representation (with some caveats) I don't see how it's RPC by any but the most broad interpretation (a function executes at another address space).
- tannhaeuser 4y ago
  The entire point of Fielding's REST was loose coupling - that you don't hard-code interactions/URLs into clients but rather discover actions/links/interaction from representations dynamically, such that the only thing a client must know a priori is a URL. "REST API" practices are criticized because they follow all the rules and brag about eg HTTP response status code semantics and whatnot, but without following HATEOAS which is the entire point of it all. I can see why teams implement "REST APIs" - to end pointless architectural meta discussions and get stuff done; and there's practical value in that. But, harsh as it sounds, and I'm apologizing in advance if this is offending to anyone, dealing with colleagues who mindlessly follow REST casuistry feels like working with hopeless rote learners, psychopathic pretenders, or unstable personalities projecting naive, irrational, and premature ideas of craftsmanship into our profession to me.
  - kareemsabri 4y ago
    I don't think that was the entire point. But who cares? Loose coupling is of little benefit to the client in a client-server pair that are implemented by the same company (which presumably Fielding wasn't picturing). There are other benefits people get from REST. Semantically understandable APIs, handlers that do one thing, predictable interfaces (this is close to as valuable as discoverable imo). I don't really get your point re: casuistry. The implementation of REST as practiced by the industry is largely pragmatic. The article appears to be arguing for REST purity.
    - masklinn 4y ago
      > I don't think that was the entire point. But who cares? People who like language to have meaning? > which presumably Fielding wasn't picturing Fielding was describing an architectural style. Although there may have been an element of advocacy, at the end of the day whether you used it or not was not his concern. > The implementation of REST as practiced by the industry is largely pragmatic. In the same sense that the implementation of airships in Boeing’s 747 is largely pragmatic, except for the part where Boeing doesn’t misscall their plane an airship. > The article appears to be arguing for REST purity. Much like saying a serval is not a dog is arguing for dog purity, yes.

dylan604 4y ago

>(JSONs fine, it's fine) I read this like you're convincing yourself vs the reader.

jakear 4y ago

GitHub’s REST api is pretty self discoverable fwiw. It kinda sucks honestly - every request yields pages of response with field after field of totally irrelevant links. Totally unparseable without json formatting and collapsing support, so CURL/wget/etc. via the terminal are painful. See for example the example response for getting an issue: https://docs.github.com/en/rest/issues/issues#get-an-issue https://docs.github.com/en/rest/issues/issues#get-an-issue And that even has omitted some fields you’d get back querying manually.

bmn__ 4y ago
> GitHub’s REST api is pretty self discoverable fwiw. I had a look at the example response to see whether that is true. I give you that there are hyperlinks existing in resources of media type `application/vnd.github+json`, but there is no uniform interface to discover a link. Fielding would disapprove. It's an indication of bad design that a client must hardcode e.g. `labels_url` instead of having a generic reusable way to access a link that works across a multitude of JSON derived media types.
- munk-a 4y ago
  Wouldn't any interface to discover links need to be hardcoded? IIRC, REST didn't actually define a unified way to describe where the links existed in the returned document.
  - bmn__ 4y ago
    That's because you're looking at the wrong place, that's not the responsibility of REST: it can't because it's not a specification, but a description of an architectural style. Instead, it's the responsibility of the media type. HTML offers hypermedia controls: hyperlinks are denoted with <a>, <area>, <base>, <link> elements and the "href" attribute; forms are denoted with the <form> element as its "action" attribute. I assume you are familiar with HTML, you can see that this is a very generalised way to find links (or controls in general), it is applicable to all HTML documents. XML has close analogues: XLink and XForms. JSON-done-right offers hypermedia controls: moral equivalent of links <https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-5.1 https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#s...>, moral equivalent of forms <https://rwcbook.github.io/hal-forms/ https://rwcbook.github.io/hal-forms/>. It is easy to reimagine `application/vnd.github+json` in the guise of this media type so that the problem I was describing earlier disappears. If a media type cannot express hypermedia controls or link relations inline (e.g. WebP images), then the HTTP header can be used instead, see RFCs 8288 and 6570.

mdaniel 4y ago

> I haven't seen a self-discoverable REST API ever in the wild I'm super cognizant this entire discussion hinges upon semantics, nuance, etc but the Okta API isn't terrible about that https://developer.okta.com/docs/reference/core-okta-api/#hypermedia https://developer.okta.com/docs/reference/core-okta-api/#hyp... I haven't personally tried `curl https://${yourOktaDomain}/api/v1 https://${yourOktaDomain}/api/v1` to see what the bootstrapping process looks like, but I can attest they do return _links in a bunch of their resource responses, and I believe their own SDK uses them, so they're not just lip service

coffee_beqn 4y ago

> a self-discoverable REST API I’ve been writing web services for over a decade and this just seems like a cute idea that is actually almost never at all useful in the real world.

kareemsabri 4y ago
Yep, there's a big gap between what's useful in Ph.D dissertations and what's useful in the business of software.
kortex 4y ago
Swagger/OpenApi is probably the closest thing to "true REST" with self-discoverable APIs. Without some sort of common schema of where/how to look for resources, there's no real automated discovery to be had without AGI. Turns out, a lot of places don't even want self-discovery. We shut off our openapi.json in prod because a) security b) we don't want bots messing around c) Hyrum's law, as soon as you expose an API endpoint, folks try to build against it and grumble if it chances/goes away. Wikipedia (along with any true wiki) is, and likely forever will be, the one true REST/HATEOAS application.