5 ms·

This essay is great. I can see from the first comments that its point is entirely lost. Which is too bad; the core idea of Representational State Transfer is in

This essay is great. I can see from the first comments that its point is entirely lost. Which is too bad; the core idea of Representational State Transfer is interesting and deserves to be respected separate from "HTTP but not SOAP". I built some of Google's first public APIs and we used SOAP, to match the onion on our belts. It never worked very well. I'm real glad that JSON over HTTP and other forms of RPC succeeded where SOAP failed. But it's a shame that Roy's ideas for REST got lost in all that.

lolinder 3y ago
Do you have any resources showing what an API client for a "true REST" system would look like? The #1 objection I've seen to REST as Fielding described it is that it seems to basically assume that the human is the API client. For example, this passage from Fielding: > A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The idea of a computer application that has no context beyond an entry URL and a media type (text/html) is pretty hard for me and many like me to wrap our heads around. I can't imagine a system being written that doesn't know what the options will be and what shape the data will come in, and once you've hard coded that it's not obvious what you gain by sending URLs instead of IDs. I'm totally open to there being something I'm missing here, but every explanation of REST I've seen focuses exclusively on the shape of the server response and doesn't explain what an API client is supposed to do with the response and how REST avoids hard-coding client actions.
- magicalhippo 3y ago
  > The #1 objection I've seen to REST as Fielding described it is that it seems to basically assume that the human is the API client. Reading the essay, it seems that is indeed the goal that the client is the human, so it would be weird for that to be an objection. If so, the objection then seems rather that a RESTful API is not terribly useful for a lot of systems. Which is fine, not everyone has to love hamburgers either. But yeah, I'd love to see a proper non-trivial example.
  - lolinder 3y ago
    The essay repeatedly uses the phrase "RESTful API", so it's natural for people to get confused when it advocates for things that are fundamentally incompatible with an API client.
- mjevans 3y ago
  Imagine a RUST endpoint as a database interface. The various HTTP operations for record read, create/update, and delete. The client could dynamically generate form formats which match the data type of records. You've probably used off the shelf CRUD software which behaves that way, only hard-coded based on settings.
- marssaxman 3y ago
  > Do you have any resources showing what an API client for a "true REST" system would look like? You are using one, this very moment, as you read this comment. Fielding's concept of "REST" was not a prescription for a new type of RPC system; it was a description of the architecture of the web as it existed at the time. The "computer application that has no context beyond an entry URL and a media type" is simply a web browser.
  - Jasper_ 3y ago
    Sure, but how is that a helpful concept in any way? If I started calling my operating system an "ALLOCBAG" and made a dissertation talking about "The ALLOCBAG Principle" you can't really deny me that it's a thing that exists ("ALLOCBAGs are all around you! You're using one I'd right now", I'd say), but it's not really advancing the state of discussion here. Similarly, rebadging "a client/server system that does a thing when you interact with the client" as "REST" (yes, I know there's a bit more to the definition) doesn't seem useful or helpful. So out it goes, in favor of the one that's talking about a style of API design. Roy Fielding designed the Adobe Experience Manager API according to his idea of REST [0]. I don't think the resulting API was remarkably noteworthy. [1] [0] https://www.slideshare.net/AEMHub2014/rest-in-aem-by-roy-fielding https://www.slideshare.net/AEMHub2014/rest-in-aem-by-roy-fie... [1] https://experienceleague.adobe.com/docs/experience-manager-65/content/assets/extending/mac-api-assets.html https://experienceleague.adobe.com/docs/experience-manager-6...
  - lolinder 3y ago
    Human UIs like HN are the only example I've ever seen that's compelling. But when you refer to it as a RESTful API (TFA uses "APIs" 31 times) you're not talking about a UI, you're talking about an Application Programming Interface, which is explicitly defined as an interface by which computers talk to each other. If REST just plain shouldn't be used in APIs then that's a fine argument to make, but we should start calling for RESTful UIs and start pointing out that a RESTful API is an oxymoron. We shouldn't be pushing for integrating HATEOAS into APIs.
- kelseyfrog 3y ago
  I wish I could have you look at a project I worked on in the early 2010s in the security industry. We had an architect who went full ham on HATEOS and honestly it was great. You could point a client at a single root endpoint and it would self-discover every other URL[path] it needed. We relied on RFCs where possible (sometimes drafts when an accepted RFC wasn't required). Everyone got very familiar with RFC 2616[1], link rels, uri templates[2], media types, &c. It required architectural dedication because junior devs would complain that it didn't match what they learned about REST from webdev tutorials. Which is to say, the social hurdles to HATEOS implementations far outweigh the technical hurdles. They'd constantly try hardcode urls and have to be reminded not to do that by the backend folks. From the backend, it was great. We had tremendous flexibility when URLs weren't part of the spec and we were able to tackle hard problems like supporting multiple simultaneous versions quickly and with little lift because of this flexibility. 1. https://www.rfc-editor.org/rfc/rfc2616 https://www.rfc-editor.org/rfc/rfc2616 2. https://www.rfc-editor.org/rfc/rfc6570 https://www.rfc-editor.org/rfc/rfc6570
- eadmund 3y ago
  > Do you have any resources showing what an API client for a "true REST" system would look like? … The idea of a computer application that has no context beyond an entry URL and a media type (text/html) is pretty hard for me and many like me to wrap our heads around. Here is a very, very simple one. It uses a hypermedia format which uses JSON syntax, but has more requirements in order to be valid: { "account_number": 12345, "balance": { "currency": "usd", "value": 100.00 }, "status": "good", "deposits": "/accounts/12345/deposits", "withdrawals": "/accounts/12345/withdrawals", "transfers": "/accounts/12345/transfers", "close-requests": "/accounts/12345/close-requests" } The key is that this is a media type (let’s call it application/example+bank-account) which defines a particular object schema, which includes certain properties whose values must be URL strings (it uses HTML’s relative-URL rules). > once you've hard coded that it's not obvious what you gain by sending URLs instead of IDs. Well, for one thing the client does not need to care about constructing URLs because it just follows them. The logic is just ‘grab the value of a key, verify that it is a URL, follow it’ rather than ‘remember an ID, use some implicit knowledge to construct a URL, follow it.’ It means that the server is free to delegate certain accounts to other servers. It makes federation a ton easier. It means that application code is able to live at a higher level.
paulddraper 3y ago
Per Fielding's definition [1], the constraints of REST architecture are: * Client-server * Stateless (no cookies/sessions) * Cache * Uniform Interface (i.e. HTTP verbs) * Layered System (proxies, load balancers, etc) * Code-on-Demand (applets, scripts) To fit the REST definition, it needs to include client-side execution of server applets/scripts. Right? This is all such a wierd game trying to defend an implausible definition. Stupid game, stupid prizes. [1] https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_st...
- wakawaka28 3y ago
  The very link you provided says that client-side execution of server code is an optional constraint: >The notion of an optional constraint may seem like an oxymoron. However, it does have a purpose in the architectural design of a system that encompasses multiple organizational boundaries. It means that the architecture only gains the benefit (and suffers the disadvantages) of the optional constraints when they are known to be in effect for some realm of the overall system. For example, if all of the client software within an organization is known to support Java applets [45], then services within that organization can be constructed such that they gain the benefit of enhanced functionality via downloadable Java classes. At the same time, however, the organization's firewall may prevent the transfer of Java applets from external sources, and thus to the rest of the Web it will appear as if those clients do not support code-on-demand. An optional constraint allows us to design an architecture that supports the desired behavior in the general case, but with the understanding that it may be disabled within some contexts. I think this means you only do it when it makes sense. Perhaps this is too open-ended as you can run basically anything on the client, including a full application. But I think the stateless requirement means you should not require that the server be bothered with the client state, and that the client state should be easily recoverable from the resource URI. But I don't actually know. You don't have to commit to using REST principles if you don't want to. I think it was proposed as a way to reduce server load and bugs, not as a way of life.
- yawaramin 3y ago
  > Stateless (no cookies/sessions) Cookies are stateless though, that's the whole point of cookies.

lolinder 3y ago

Do you have any resources showing what an API client for a "true REST" system would look like? The #1 objection I've seen to REST as Fielding described it is that it seems to basically assume that the human is the API client. For example, this passage from Fielding: > A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The idea of a computer application that has no context beyond an entry URL and a media type (text/html) is pretty hard for me and many like me to wrap our heads around. I can't imagine a system being written that doesn't know what the options will be and what shape the data will come in, and once you've hard coded that it's not obvious what you gain by sending URLs instead of IDs. I'm totally open to there being something I'm missing here, but every explanation of REST I've seen focuses exclusively on the shape of the server response and doesn't explain what an API client is supposed to do with the response and how REST avoids hard-coding client actions.

magicalhippo 3y ago
> The #1 objection I've seen to REST as Fielding described it is that it seems to basically assume that the human is the API client. Reading the essay, it seems that is indeed the goal that the client is the human, so it would be weird for that to be an objection. If so, the objection then seems rather that a RESTful API is not terribly useful for a lot of systems. Which is fine, not everyone has to love hamburgers either. But yeah, I'd love to see a proper non-trivial example.
- lolinder 3y ago
  The essay repeatedly uses the phrase "RESTful API", so it's natural for people to get confused when it advocates for things that are fundamentally incompatible with an API client.
mjevans 3y ago
Imagine a RUST endpoint as a database interface. The various HTTP operations for record read, create/update, and delete. The client could dynamically generate form formats which match the data type of records. You've probably used off the shelf CRUD software which behaves that way, only hard-coded based on settings.
marssaxman 3y ago
> Do you have any resources showing what an API client for a "true REST" system would look like? You are using one, this very moment, as you read this comment. Fielding's concept of "REST" was not a prescription for a new type of RPC system; it was a description of the architecture of the web as it existed at the time. The "computer application that has no context beyond an entry URL and a media type" is simply a web browser.
- Jasper_ 3y ago
  Sure, but how is that a helpful concept in any way? If I started calling my operating system an "ALLOCBAG" and made a dissertation talking about "The ALLOCBAG Principle" you can't really deny me that it's a thing that exists ("ALLOCBAGs are all around you! You're using one I'd right now", I'd say), but it's not really advancing the state of discussion here. Similarly, rebadging "a client/server system that does a thing when you interact with the client" as "REST" (yes, I know there's a bit more to the definition) doesn't seem useful or helpful. So out it goes, in favor of the one that's talking about a style of API design. Roy Fielding designed the Adobe Experience Manager API according to his idea of REST [0]. I don't think the resulting API was remarkably noteworthy. [1] [0] https://www.slideshare.net/AEMHub2014/rest-in-aem-by-roy-fielding https://www.slideshare.net/AEMHub2014/rest-in-aem-by-roy-fie... [1] https://experienceleague.adobe.com/docs/experience-manager-65/content/assets/extending/mac-api-assets.html https://experienceleague.adobe.com/docs/experience-manager-6...
- lolinder 3y ago
  Human UIs like HN are the only example I've ever seen that's compelling. But when you refer to it as a RESTful API (TFA uses "APIs" 31 times) you're not talking about a UI, you're talking about an Application Programming Interface, which is explicitly defined as an interface by which computers talk to each other. If REST just plain shouldn't be used in APIs then that's a fine argument to make, but we should start calling for RESTful UIs and start pointing out that a RESTful API is an oxymoron. We shouldn't be pushing for integrating HATEOAS into APIs.
kelseyfrog 3y ago
I wish I could have you look at a project I worked on in the early 2010s in the security industry. We had an architect who went full ham on HATEOS and honestly it was great. You could point a client at a single root endpoint and it would self-discover every other URL[path] it needed. We relied on RFCs where possible (sometimes drafts when an accepted RFC wasn't required). Everyone got very familiar with RFC 2616[1], link rels, uri templates[2], media types, &c. It required architectural dedication because junior devs would complain that it didn't match what they learned about REST from webdev tutorials. Which is to say, the social hurdles to HATEOS implementations far outweigh the technical hurdles. They'd constantly try hardcode urls and have to be reminded not to do that by the backend folks. From the backend, it was great. We had tremendous flexibility when URLs weren't part of the spec and we were able to tackle hard problems like supporting multiple simultaneous versions quickly and with little lift because of this flexibility. 1. https://www.rfc-editor.org/rfc/rfc2616 https://www.rfc-editor.org/rfc/rfc2616 2. https://www.rfc-editor.org/rfc/rfc6570 https://www.rfc-editor.org/rfc/rfc6570
eadmund 3y ago
> Do you have any resources showing what an API client for a "true REST" system would look like? … The idea of a computer application that has no context beyond an entry URL and a media type (text/html) is pretty hard for me and many like me to wrap our heads around. Here is a very, very simple one. It uses a hypermedia format which uses JSON syntax, but has more requirements in order to be valid: { "account_number": 12345, "balance": { "currency": "usd", "value": 100.00 }, "status": "good", "deposits": "/accounts/12345/deposits", "withdrawals": "/accounts/12345/withdrawals", "transfers": "/accounts/12345/transfers", "close-requests": "/accounts/12345/close-requests" } The key is that this is a media type (let’s call it application/example+bank-account) which defines a particular object schema, which includes certain properties whose values must be URL strings (it uses HTML’s relative-URL rules). > once you've hard coded that it's not obvious what you gain by sending URLs instead of IDs. Well, for one thing the client does not need to care about constructing URLs because it just follows them. The logic is just ‘grab the value of a key, verify that it is a URL, follow it’ rather than ‘remember an ID, use some implicit knowledge to construct a URL, follow it.’ It means that the server is free to delegate certain accounts to other servers. It makes federation a ton easier. It means that application code is able to live at a higher level.

paulddraper 3y ago

Per Fielding's definition [1], the constraints of REST architecture are: * Client-server * Stateless (no cookies/sessions) * Cache * Uniform Interface (i.e. HTTP verbs) * Layered System (proxies, load balancers, etc) * Code-on-Demand (applets, scripts) To fit the REST definition, it needs to include client-side execution of server applets/scripts. Right? This is all such a wierd game trying to defend an implausible definition. Stupid game, stupid prizes. [1] https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_st...

wakawaka28 3y ago
The very link you provided says that client-side execution of server code is an optional constraint: >The notion of an optional constraint may seem like an oxymoron. However, it does have a purpose in the architectural design of a system that encompasses multiple organizational boundaries. It means that the architecture only gains the benefit (and suffers the disadvantages) of the optional constraints when they are known to be in effect for some realm of the overall system. For example, if all of the client software within an organization is known to support Java applets [45], then services within that organization can be constructed such that they gain the benefit of enhanced functionality via downloadable Java classes. At the same time, however, the organization's firewall may prevent the transfer of Java applets from external sources, and thus to the rest of the Web it will appear as if those clients do not support code-on-demand. An optional constraint allows us to design an architecture that supports the desired behavior in the general case, but with the understanding that it may be disabled within some contexts. I think this means you only do it when it makes sense. Perhaps this is too open-ended as you can run basically anything on the client, including a full application. But I think the stateless requirement means you should not require that the server be bothered with the client state, and that the client state should be easily recoverable from the resource URI. But I don't actually know. You don't have to commit to using REST principles if you don't want to. I think it was proposed as a way to reduce server load and bugs, not as a way of life.
yawaramin 3y ago
> Stateless (no cookies/sessions) Cookies are stateless though, that's the whole point of cookies.