In a previous post I mentioned I had been working on replicating some functionality for collecting beneficiaries data in an old SPA.
The code in that application was quite legacy and highly coupled to an existing API. It was poorly tested, and even those tests did not have a make command to run locally nor were they running in the CI pipeline.
It consisted of a Sinatra application that acts as a proxy between a React frontend and a backend API. For a long time, this proxy only knew about one API, so everything was built around that single dependency.
Then I needed to add support for a new API. But first, I had to isolate anything that was coupled to the existing API, thus making room for the upcoming changes.
In the examples below, I have omitted code that is unnecessary to understand the process, such as logging and observability instrumentation.
The initial setup
The backend application is very simple. The entry point is config.ru, which maps routes to different Rack apps via a Dispatcher:
# system/infrastructure/dispatcher.rb
module Infrastructure
Dispatcher = Rack::Builder.app do
map '/' do
run System::Server
end
map '/api' do
run System::Proxy
end
end
end
The server handles static file serving for the React SPA:
# system/server.rb
module System
class Server < Sinatra::Base
set root: File.expand_path('..', __dir__)
not_found do
render_static_file
end
get '/' do
render_static_file
end
private
def render_static_file
File.read(File.join('public', 'index.html'))
end
end
end
The proxy delegates to a request handler, where the actual API proxying happens:
# system/request_handler.rb
module System
class RequestHandler
UNAUTHORIZED_CODE = 401
ALLOWED_PATHS = %w(
/beneficiary_collections
)
ALLOWED_METHODS = %w(GET PUT PATCH POST)
HEADERS = { 'Content-Type' => 'application/json' }
def initialize(env)
@request = Rack::Request.new(env)
end
def call
return render(UNAUTHORIZED_CODE, { error: 'Unauthorized' }.to_json) if invalid_path && invalid_request_method
response = # HTTParty logic
render(response.code, response.body)
end
private
def invalid_path
!ALLOWED_PATHS.include?(path)
end
def invalid_request_method
!ALLOWED_METHODS.include?(@request.request_method)
end
def render(status, body)
[status, HEADERS, [body]]
end
def api_url
ENV['API_BASE_URL']
end
# other private methods omitted
end
end
If you look closely at the call method, the guard clause uses && instead of ||. This means it only returns unauthorized when both the path and the method are invalid, not when either one is. This was a bug that was present from the start and that I would fix later as part of this process.
Notice that api_url always returns the same environment variable regardless of the request path. The whole request handler assumes there is only one API.
First changes: routing through the proxy
Here is something I had not noticed before: in the local development environment, the frontend was bypassing the proxy entirely. The webpack dev server was configured to send API requests directly to the API stub.
The webpack dev server configuration was as follows:
// client/webpack/webpack.development.js
const API_BASE_URL = process.env.API_BASE_URL || 'http://beneficiary_collections_api:5300';
module.exports = {
// ...
devServer: {
host: '0.0.0.0',
port: 3001,
allowedHosts: 'all',
historyApiFallback: true,
proxy: {
'/api': {
target: API_BASE_URL,
pathRewrite: { '^/api': '' }
},
// ...
}
}
}
The pathRewrite stripped the /api prefix and sent requests straight to the stub. This meant the Sinatra proxy was never involved in local development. Consequently, you cannot test routing if you are skipping the proxy.
To fix this, I added a backend service to docker-compose.yml and renamed app to frontend:
services:
frontend:
ports:
- 3001:3001
depends_on:
- backend
command: npm start
backend:
ports:
- 8080:8080
depends_on:
- beneficiary_collections_api
command: bundle exec rerun --dir . --pattern "**/*.{rb}" --background -- rackup --port=8080 -o 0.0.0.0 config.ru
beneficiary_collections_api:
build:
context: ./stubs/beneficiary_collections_api
ports:
- 5300:5300
command: bundle exec rerun --dir . --background -- rackup --port=5300 -o 0.0.0.0 config.ru
I installed the rerun gem so the backend application would automatically restart when any Ruby file changed.
Note that the page still needs to be reloaded in the browser. Until the backend is fully reloaded, requests will return a 504 error.
Then I updated the webpack dev server to point at the backend instead of the API stub directly:
// client/webpack/webpack.development.js
const BACKEND_URL = process.env.BACKEND_URL || 'http://backend:8080';
module.exports = {
// ...
devServer: {
host: '0.0.0.0',
port: 3001,
allowedHosts: 'all',
historyApiFallback: true,
proxy: {
'/api': {
target: BACKEND_URL
},
// ...
}
}
}
No more pathRewrite. The /api prefix is now kept as-is, and the backend proxy handles it from there. This matches how the application works in staging and production.
Finally, I refactored the scarce tests to route them through the Dispatcher instead of testing the proxy in isolation, and added the make command to be able to run those tests locally:
# spec/requests/api/proxy_spec.rb
RSpec.describe 'Proxy' do
include Rack::Test::Methods
def app
Infrastructure::Dispatcher
end
context 'when beneficiary_collections' do
let(:base_url) { 'https://beneficiary-collections.lol' }
before do
allow(ENV).to receive(:[]).with('API_BASE_URL').and_return(base_url)
stub_request(:get, "#{base_url}/beneficiary_collections")
.to_return(status: 200, body: { message: 'Success' }.to_json)
stub_request(:get, "#{base_url}/beneficiary_collections/invalid")
.to_return(status: 401, body: { message: 'Unauthorized' }.to_json)
end
context 'when the URL is allowed' do
it 'returns a 200 status code' do
get '/api/beneficiary_collections'
expect(last_response.status).to eq(200)
end
end
context 'when the URL is not allowed' do
it 'returns a 401 status code' do
get '/api/beneficiary_collections/invalid'
expect(last_response.status).to eq(401)
end
end
end
end
Isolating the old API
I applied a set of changes in both the frontend and the backend.
The key backend change was making api_url conditional in the request handler instead of returning always the same environment variable (properly renamed below):
# system/request_handler.rb
def api_url
if path.start_with?('/beneficiary_collections')
ENV['BENEFICIARY_COLLECTIONS_API_BASE_URL']
end
end
The tests were properly updated, too, adding a specific context for the beneficiary collections API.
On the frontend side, the template that renders the beneficiary collection form was extracted from the page where it was being rendered, so it could be easily duplicated later. I also updated the existing test suite using React Testing Library, adding a new context to ensure the extracted components still behaved correctly in isolation.
Adding the new API
With the groundwork done, adding the new API was straightforward.
On the React side, a new route was added:
// client/src/pages/App/App.js
import Home from 'pages/Home';
import CollectionRequestsHome from 'pages/CollectionRequestsHome';
function App() {
return (
<Router>
<ContextWrapper>
<Switch>
<Route exact path="/" component={Home} />
<Route exact path="/collection_requests" component={CollectionRequestsHome} />
</Switch>
</ContextWrapper>
</Router>
);
}
export default App;
All components were duplicated and adapted to the collection requests form, including the endpoints specific to the new API. Every change on the frontend was accompanied by new unit and integration tests.
On the backend, the request handler received several improvements:
All constants are frozen.
The status code for invalid requests was changed from 401 to 404, which is more semantically correct.
The validation methods became proper predicate methods.
An attribute reader was added for the request.
The api_url method now routes based on the request path prefix.
# system/request_handler.rb
module System
class RequestHandler
NOT_FOUND_STATUS_CODE = 404
ALLOWED_PATHS = %w[
/beneficiary_collections
/collection_requests
].freeze
ALLOWED_METHODS = %w[GET PUT PATCH POST].freeze
HEADERS = { 'Content-Type' => 'application/json' }
def initialize(env)
@request = Rack::Request.new(env)
end
def call
if invalid_path_info? || invalid_request_method?
return render(NOT_FOUND_STATUS_CODE, { error: 'Not found' }.to_json)
end
response = # HTTParty logic
render(response.code, response.body)
end
private
attr_reader :request
def invalid_path_info?
!(request.path_info.match?(Regexp.union(ALLOWED_PATHS)))
end
def invalid_request_method?
!(ALLOWED_METHODS.include?(request.request_method))
end
def render(status, body)
[status, HEADERS, [body]]
end
def api_url
if path.start_with?('/beneficiary_collections')
ENV['BENEFICIARY_COLLECTIONS_API_BASE_URL']
elsif path.start_with?('/collection_requests')
ENV['COLLECTION_REQUESTS_API_BASE_URL']
end
end
# other private methods omitted
end
end
The server needed a new route too:
# system/server.rb
get '/collection_requests/' do
render_static_file
end
That trailing slash on get '/collection_requests/' will come back to haunt me.
A new stub application was added for the collection requests API, and docker-compose.yml was updated to include it:
services:
collection_requests_api:
build:
context: ./stubs/collection_requests_api
ports:
- 5301:5301
command: bundle exec rerun --dir . --background -- rackup --port=5301 -o 0.0.0.0 config.ru
A new context block for the collection requests API was added to the proxy test, mirroring the beneficiary collections one.
The trailing slash problem
The code was working perfectly locally. Tests were green. It got merged and deployed to staging. And then the collection requests form did not render.
The issue turned out to be a trailing slash added to the route, while React router navigated to /collection_requests, without the trailing slash.
Sinatra does not treat these the same way by default, and it is well documented in their FAQ section.
The fix was to make the route accept both:
# system/server.rb
get '/collection_requests/?' do
render_static_file
end
The /? at the end makes the trailing slash optional. The not_found handler was also restored so that unknown routes would still serve the SPA. It returns a 404 status code so the React app can show its own not found page.
On the frontend, the webpack dev server configuration also changed. The historyApiFallback option was replaced with a custom middleware that validates routes and handles trailing slashes:
// client/webpack/webpack.development.js
const VALID_PATHS = ['/', '/collection_requests'];
module.exports = {
historyApiFallback: false,
setupMiddlewares: (middlewares, devServer) => {
devServer.app.get('*', (req, res, next) => {
if (req.headers.accept?.includes('text/html')) {
const normalizedPath = req.path.replace(/\/$/, '') || '/';
if (!VALID_PATHS.includes(normalizedPath)) {
res.status(404);
}
req.url = '/index.html';
}
next();
});
return middlewares;
},
Not very elegant, but it works.
The React app also got a catch-all route for unknown paths, with a NotFound component:
// client/src/pages/App/App.js
import NotFound from 'pages/NotFound';
// ...
<Route path="*" component={NotFound} />
I also added minimal testing for the server to cover both with and without trailing slash:
# spec/requests/server_spec.rb
RSpec.describe 'Server' do
include Rack::Test::Methods
def app
Infrastructure::Dispatcher
end
before do
allow(File).to receive(:read).and_call_original
allow(File).to receive(:read).with(File.join('public', 'index.html')).and_return('html content')
end
context 'when path is /' do
it 'returns a 200 status code and HTML content' do
get '/'
expect(last_response.status).to eq(200)
expect(last_response.headers['Content-Type']).to include('text/html')
end
end
context 'when path is /collection_requests' do
it 'returns a 200 status code and HTML content' do
get '/collection_requests'
expect(last_response.status).to eq(200)
expect(last_response.headers['Content-Type']).to include('text/html')
end
end
context 'when path is /collection_requests/' do
it 'returns a 200 status code and HTML content' do
get '/collection_requests/'
expect(last_response.status).to eq(200)
expect(last_response.headers['Content-Type']).to include('text/html')
end
end
context 'when path is invalid' do
it 'returns a 404 status code and HTML content' do
get '/invalid'
expect(last_response.status).to eq(404)
expect(last_response.headers['Content-Type']).to include('text/html')
end
end
end
To prevent this from happening again, I added some make commands to run the application in production mode locally:
# Makefile
.PHONY: prod/up prod/down prod/build
prod/up:
docker compose -f docker-compose.prod.yml up
prod/down:
docker compose -f docker-compose.prod.yml up
prod/build:
docker compose -f docker-compose.prod.yml build
The dedicated docker-compose file is as follows:
# docker-compose.prod.yml
services:
app:
ports:
- 8080:80
depends_on:
- beneficiary_collections_api
- collection_requests_api
environment:
- NODE_ENV=production
beneficiary_collections_api:
build:
context: ./stubs/beneficiary_collections_api
ports:
- 5300:5300
volumes:
- ./stubs/beneficiary_collections_api:/opt/stubs
command: bundle exec rerun --dir . --background -- rackup --port=5300 -o 0.0.0.0 config.ru
collection_requests_api:
build:
context: ./stubs/collection_requests_api
ports:
- 5301:5301
volumes:
- ./stubs/collection_requests_api:/opt/stubs
command: bundle exec rerun --dir . --background -- rackup --port=5301 -o 0.0.0.0 config.ru
From now on, catching the kind of failure caused by trailing slashes locally is way easier.
Conclusion
Adding support for a new API provided an opportunity to harden a legacy application. We moved from a poorly tested setup that bypassed its own proxy locally to a robust environment with proper routing and test coverage.
The challenges I faced, from the logic bug in the guard clause to the trailing slash discrepancy, demonstrate why dev-to-production parity is essential. With these changes in place, the application is no longer tied to a single dependency, and the team can now develop and test new features with the confidence that "working locally" actually means "working in production."
Thank you for reading and see you in the next one!
