Hacker News Reader

Comment by potamic | Hacker News Reader

Great article. Calling APIs RESTful because they return JSON has always been a peeve of mine. But here's the question though, why do APIs need to be RESTful? What is the need for a client to have no knowledge of the server, if the server can also provide logic that can run on the client. In some sense, one could argue that a service that provides both raw data and client logic to transform raw data to hypermedia, is still very much in the spirit of REST. Webapps by definition must satisfy this requirement, so it is moot to be asking if a webapp follows RESTful principles. Of course it does, it runs on the web! Native apps on the other hand have sure ruined everything.

View on HN

IMHO, they've wildly missed the mark. APIs, as colloquially known, can't be RESTful as they define it because the client systems aren't AI based and can't follow links. To use their example:

  <html>
      <body>
          <div>Account number: 12345</div>
          <div>Balance: $100.00 USD</div>
          <div>Links:
            <a href="/accounts/12345/deposits">deposits</a>
            <a href="/accounts/12345/withdrawals">withdrawals</a>
            <a href="/accounts/12345/transfers">transfers</a>
            <a href="/accounts/12345/close-requests">close-requests</a>
        </div>
    <body>
  </html>

I can navigate to that page and because I know English can follow links to my withdrawls and deposits. A computer can't. The client program needs to have an understanding of withdrawl and deposit in order to function. The only way to do that involves coupling the client to the server.

> The client program needs to have an understanding of withdrawl and deposit in order to function. The only way to do that involves coupling the client to the server.

Rest never denied that coupling, it defined that coupling at the content-type level.

Can you expand? I don't think I understand.

In Fielding’s REST, the exchange is defined in terms of the document contents (the content types). These are what define the interaction both ways, both in terms of data and in terms of navigating the set and interacting with it (think links and forms).

The client necessarily has to know about that. That’s where the coupling happens. Where the coupling doesn’t happen is in things like resource names and locations, as far as Fielding’s thesis was concerned there’s only one location the client needs to know and it’s the root location, everything else can be obtained by navigating the service.

>Where the coupling doesn’t happen is in things like resource names and locations, as far as Fielding’s thesis was concerned there’s only one location the client needs to know and it’s the root location, everything else can be obtained by navigating the service

Yeah, any my point is that relies on the client (i.e. a human) being able to understand what the different links mean. A programmatic client can't do that without in someway hard coding the structure of the API.

> A programmatic client can't do that without in someway hard coding the structure of the API.

That's false. Here is the HTML again, augmented with a link relation which by its nature is perfectly understandable to a program.

    <a href="/accounts/12345/deposits" rel="https://schema.org/DepositAccount">deposits</a>

Anyone can coin a link relation on the Web, as long as its identifier is a URI. Tokens are reserved and need to be registered at IANA: https://www.iana.org/assignments/link-relations

It's understandable if you write the code for the program to understand. If it changes from deposits to credits tomorrow then your program breaks. Hence it's coupled to the server.

There is always coupling. The question is whether a certain architectural design is coupled loosely or tightly. If you read Fielding's blog post referenced in TFA, you can see he is an advocate of loose coupling.

I have demonstrated this design in my post above.

And that's even before we get into:

* Localization * Accessibility * Different clients * Different presentations for different contexts.

The whole premise of RESTful hyper-media driven APIs described in this article is predicated on "The One" client talking to the server. Our modern world is not this.

Why should a server limit itself to a single client? At some point, you might want to make a mobile app companion to your site, or you might white-label your services in partnership with another company who will need to use your APIs, or any number of other common scenarios.

A hobbyist / small company doesn't need to have RESTful APIs. The whole point is to design them so that they play well with others, and when you get to that point, you (or more likely the people who depend on you) will wish you had.

> you might white-label your services in partnership with another company who will need to use your APIs,

As soon as you have a third party using your API things get another layer of conplexity: do you charge them? Do you rate limit them? if you have several partners, how do you authenticate them? etc.

API gateway solve some of that, and sometimes you dont care, but generally its not as sinple as goving your internal API to people and telling them to go wild

Of course it isn't that simple- most of the additional challenges you mentioned are business problems, though, not technical, and are generally orthogonal to the actual design of the API.

The biggest hurdle to opening up your API is usually needing to move from a single tenant to a multi-tenant architecture in your database.

Some tenants will have regulatory burdens you need to meet, and your early adopters will likely have a slew of requests that you'll need to decide on- do you risk tailoring your application to their needs with features future clients won't want?

To these last points, I think RESTful architecture helps, rather than hinders, but YMMV.

> What is the need for a client to have no knowledge of the server, if the server can also provide logic that can run on the client

It's a measure of decoupling I think. If your client started out with no knowledge of the server and still managed to work, then it will still work even when the server is upgraded, restructured, etc etc.

Of course, having every client just started at the root URL and then navigate its way to what it needs by effectively spidering the server just aint practical in any meaningful sense. But in small ways and critical places it is still possible to follow this pattern, and to the extent you do, in return you get a level of decoupling that is a useful property to have.

Reply on news.ycombinator.com