Decoupling REST API and Frontend Web Application

design-patternsrestruby-on-rails

I'm learning Ruby on Rails coming from Node.js/express and had a few design questions. I used React.js for the frontend in my Node apps and I'm planning on continuing to do so in my Rails apps.

What I was doing in Node.js

Have all requests starting with / be handled by a "view router". This essentially serves all the HTML and any injected JSON. For example:

mywebsite.com/profile will serve HTML of the user's profile.

Have any requests starting with /api be handled by an "API router". This had the REST API routes to access resources.

GET mywebsite.com/api/profile serves the JSON for the profile.

The React app loaded in profile.html for example would make an HTTP request to GET mywebsite.com/api/profile and populate the view. (Of course, I could've just injected the profile via EJS, but this is an example use case)

Note that both these routers were running on the same server/IP

What I'm thinking of doing with Rails

I'm planning to build more complex apps that have both a web client, and native mobile clients. This means that I will need a stateless REST server. I read this guide about generating an "API only" Rails app which got me thinking about making the REST API its own server, maybe under api.mywebsite.com and have all the views be served from mywebsite.com. The former would be an API only Rails app, and the latter would be a normal Rails app that serves views.

Also, as a side question, I was reading the rails-react Doctrine and was having trouble finding some downsides. If someone with knowledge of it can provide the other side of the story, it would be much appreciated!

For an app that could potentially get complicated and have to scale, is decoupling the REST API and the View a good idea? What do companies like Twitter and Github (both use or used to use Rails I believe) do?

Best Answer

I can't speak for Twitter and Github, but I can speak for Stack Overflow.

I wouldn't worry about "scale" as an abstract possible idea. I would worry about your present and provable needs from the next 6-12 months. Scaling requires much work, measurement and tweaking which can't really be anticipated. For example, Stack Overflow needs only a few parts to be split into services. Most of the application is happily monolithic.
One thing that Github certainly does and Twitter does not is rendering on the server, as well as on the client. We also do this. The reason is performance: no one likes to wait for a page to load and then wait for the content to load. It has been shown that even adding 0.1s to a page load time negatively impacts engagement in a substantial way.

As a consequence of this, I would not worry too much about the URL structure for the API. I would worry instead to build a shared framework that can be used on both the front end and the back end to access data, and then exposed as pages or APIs independently.

Related Solutions

Handling Resource Identifiers in REST API Clients

Edited to address question updates, previous answer removed

Looking over your changes to your question I think I understand the problem you are facing a bit more. As there is no field that is an identifier on your resources (just a link) you have no way to refer to that specific resource within your GUI (i.e. a link to a page describing a specific pet).

The first thing to determine is if a pet ever makes sense without an owner. If we can have a pet without any owner then I would say we need some sort of unique property on the pet that we can use to refer to it. I do not believe this would violate not exposing the ID directly as the actual resource ID would still be tucked away in a link that the REST client wouldn't parse. With that in mind our pet resource may look like:

<Entity type="Pet">
    <Link rel="self" href="http://example.com/pets/1" />
    <Link rel="owner" href="http://example.com/people/1" />
    <UniqueName>Spot</UniqueName>
</Entity>

We can now update the name of that pet from Spot to Fido without having to mess with any actually resource IDs throughout the application. Likewise we can refer to that pet in our GUI with something like:

http://example.com/GUI/pets/Spot

If the pet does not make any sense without an owner (or pets are not allowed in the system without an owner) then we can use the owner as part of the "identity" of the pet in the system:

http://example.com/GUI/owners/John/pets/1 (first pet in the list for John)

One small note, if both Pets and People can exist separate of each-other I would not make the entry point for the API the "People" resource. Instead I would create a more generic resource that would contain a link to People and Pets. It could return a resource that looks like:

<Entity type="ResourceList">
    <Link rel="people" href="http://example.com/api/people" />
    <Link rel="pets" href="http://example.com/api/pets" />
</Entity>

So by only knowing the first entry point into the API and not processing any of the URLs to figure out system identifiers we can do something like this:

User logs into the application. The REST client accesses the entire list of people resources available which may look like:

<Entity type="Person">
    <Link rel="self" href="http://example.com/api/people/1" />
    <Pets>
        <Link rel="pet" href="http://example.com/api/pets/1" />
        <Link rel="pet" href="http://example.com/api/pets/2" />
    </Pets>
    <UniqueName>John</UniqueName>
</Entity>
<Entity type="Person">
    <Link rel="self" href="http://example.com/api/people/2" />
    <Pets>
        <Link rel="pet" href="http://example.com/api/pets/3" />
    </Pets>
    <UniqueName>Jane</UniqueName>
</Entity>

The GUI would loop through each resource and print out a list item for each person using the UniqueName as the "id":

<a href="http://example.com/gui/people/1">John</a>
<a href="http://example.com/gui/people/2">Jane</a>

While doing this it could also process each link that it finds with a rel of "pet" and get the pet resource such as:

<Entity type="Pet">
    <Link rel="self" href="http://example.com/api/pets/1" />
    <Link rel="owner" href="http://example.com/api/people/1" />
    <UniqueName>Spot</UniqueName>
</Entity>

Using this it can print a link such as:

<!-- Assumes that a pet can exist without an owner -->
<a href="http://example.com/gui/pets/Spot">Spot</a>

<!-- Assumes that a pet MUST have an owner -->
<a href="http://example.com/gui/people/John/pets/Spot">Spot</a>

If we go with the first link and assume that our entry resource has a link with a relation of "pets" the control flow would go something like this in the GUI:

Page is opened and the pet Spot is requested.
Load the list of resources from the API entry point.
Load the resource that is related with the term "pets".
Look through each resource from the "pets" response and find one that matches Spot.
Display the information for spot.

Using the second link would be a similar chain of events with the exception being that People is the entry point to the API and we would first get a list of all people in the system, find the one that matches, then find all pets that belong to that person (using the rel tag again) and find the one that is named Spot so we can display the specific information related to it.

Rest – Decoupling Server and Client using REST API

JSON/HTTP is a really good decoupling mechanism, and I'll throw out a couple of suggestions that will make it even more loosely coupled.

The rapid industry adoption of JSON/HTTP interfaces really speaks well about how people view the usefulness of that model.

Enforce a MUST IGNORE rule.

That is, when parsing the JSON (client or server), the app MUST IGNORE any fields it don't recognize.

XML went in the with idea that the app MUST UNDERSTAND each field or else the document was invalid. But that created problems with versioning, because with almost any change, clients needed to upgrade every time the server did. Even adding an informational field broke the spec. With MUST IGNORE, the server can add new fields any time, and as long as it doesn't remove or change the meaning of other fields (see below). Existing clients can just ignore the new fields. Rather, they MUST IGNORE the new fields.

A search on MUST IGNORE and MUST UNDERSTAND will reveal lots of good articles that talk about that.

Minimize breaking changes.

A "breaking change" is a change that will break existing clients. That is, removing a field the clients use. Or changing the meaning of a field (i.e. changing an amount field from dollars to Yen). That is, something that invalidates a client's assumptions about the data it's currently using.

With a breaking change, every client needs to make a change to support the new semantics or stop relying on missing fields. Do don't do that unless its necessary.

The next logical step gets kind of contentious -- but in the extreme you would never make a breaking change. That is, have full backward-compatibility for every release. That may or may not be realistic, and it may require carrying along baggage from early versions, but it will spare a lot of churn for the clients.

OAuth 2 is a really good bet for a well-thought out, standardized security protocol. You could sit down and design something simpler, depending on what compromises are OK. But OAuth is a good fleshed-out protocol that has undergone years of industry scrutiny, so they've had lots of time to work out the kinks. And standard libraries are readily available for both client and server. I used an OAuth plugin to DJango for one project and it worked out really well.
Because of the ubiquity of JSON parsers, maintaining a single API regardless of client will make life a lot easier. Sometimes it doesn't work out -- sometimes a client can only understand XML or some proprietary protocol, but starting simple & adding complexity makes life easier.