API + SPA Deployment Best Practices

Question

Developing a SPA in the frontend (with Vue.js) which consumes endpoints from a (Laravel) API in the backend introduces some challenges that need to be tackled:

1. How to sync deployment when introducing new backend/frontend code

If the code is separated in two VCS repositories (frontend/backend) it can be challenging to sync deployment of both frontend and backend making sure that both finish at the exact same time. Otherwise this can lead to unexpected behaviour (e.g. calling endpoints that are not yet deployed or have changed). Anyone came up with a great solution for this? What is your best practice to tackle this problem? What if versioning every little change is not an option?

2. How to make sure that the frontend code of the SPA is being refreshed after deployment?

So you managed to keep your deployments in sync (see problem 1.), but how do you make sure that the SPA code of every currently active end user is being refreshed? With webpack code splitting enabled, the application might break immediately for users that are currently using your app in between a deployment.

How do you make sure that your users are being served the latest JS without having them reload the entire application on every request? What are best practices (besides forcing the user to refresh the entire page via websockets)? Are there solutions that allow currently active users to keep using the application without being forced to refresh while they might just finished something that's ready to be saved?

I am very interested in your findings, learnings and solutions!

Answer 1

1. How to sync deployment when introducing new backend/frontend code

The best practice here is to keep the backend and frontend in the same repo. You can, of course, extract some reusable code out of them to use in other projects but the code base should ideally be in the same repo or you will keep facing these frustrating code sync issues. Even if you look at popular Laravel libraries - they all have the frontend and backend in the same repo.

If that's not option, I would suggest that you use a versioning system that can link the versions of both repos. Yep, that means versioning every little change!

2. How to make sure that the frontend code of the SPA is being refreshed after deployment?

Usually, I'd avoid doing stuff to force a refresh on the client codebase but if you have long user sessions, it may actually make sense.

To do that, you can use any web socket implementation (such as Pusher) and have your CI notify the frontend through web sockets of any deployment. The frontend can then queue a page refresh. Check out this article on how to implement.

Answer 2

The two questions are tightly coupled and can't be answered separately in my opinion. I have some possibile strategies to deal with such a scenario:

1. Never introduce breaking changes in the API

API deployments should be incremental without breaking anything for users using the previous version. In this way you can simply push the changes on your backend and when the backend deployment is completed you deploy the frontend. Easily achieved if you have separate projects. This can be performed for major releases by prefixing the API with the version:

https://website.url/api/v${version}/${endpoint}

while minor deployments should only be minor adjustments/bugfixes that do not break frontend functionality.

This approach is the best because it ensures absolutely no downtime in the user activity, but requires additional work and may not be feasible in many projects. If the backend does not introduce breaking changes, you can implement a simple polling system (with a long timespan, such as minutes) from the frontend that detects if a reload in necessary to load the new frontend deployment.

2. Standard response for outdated requests

• Each request from the frontend includes an information about the version in use by the frontend. It could be a standard header, a param, whatever. You should wrap your requests in a function that add the information before sending the request itself.

• If the server detects a request from an outdated frontend, it returns a standard response, such as:

{
    "error": "update required"
}

• The frontend detects the error and reload the page

I honestly don't like this approach, because the request may be a POST request with some form data and a page reload may lose the user all their input, which is annoying.