How Structured Thinking Transformed REST API Design

Harman Singh Sandhu | First-year BTech CSE at JIIT Noida | BS Data Science at IIT Madras

---

Executive Summary

While developing the backend for Ace Rentals, an architectural weakness was identified in how authorization was enforced. Authorization checks were duplicated across individual API routes, increasing maintenance overhead and introducing the risk of inconsistent access control as the system scaled.

The issue was structural rather than functional. Authorization relied on developers manually adding checks in each route instead of being enforced consistently by the architecture. This approach does not scale and increases fragility as the number of routes and features grows.

Given that the API was already in active use, a full redesign was not viable. The solution needed to operate within the existing Express framework, preserve current behavior, and focus narrowly on improving authorization structure.

To address this, authorization logic was centralized into middleware and routes were reorganized around resources. Ownership checks now execute consistently before any business logic, shifting access control from an implementation detail to an architectural guarantee.

This change eliminated duplicated logic, simplified route handlers, and made authorization predictable by default. A subsequent qualitative risk assessment confirmed that core business logic is stable, while remaining risks are primarily structural and related to shared authorization and setup. These insights will guide further architectural exploration, which will be evaluated and documented in a follow-up post.

Key takeaways: Problems that show up repeatedly in code are often design issues, not implementation mistakes. Rules like authorization that apply across many routes should be enforced in one shared place rather than copied everywhere. Good system design reduces the chance of human error and makes growth easier to manage.

---

Setting the Context: From Working Code to Structural Issues

Before diving into the redesign, it’s important to understand how the original structure evolved and why it became a problem.

While building Ace Rentals, a listings and reviews website, authorization logic evolved gradually alongside new features. As actions like deleting listings and reviews were added, it became necessary to ensure that users could only modify or remove resources they owned.

What started as simple ownership checks eventually exposed deeper design concerns. This article reflects on how applying structured thinking helped me move from scattered authorization logic to a centralized, middleware-based approach, improving clarity, maintainability, and confidence in the system as it grew.

Understanding the Problem: Scattered Authorization Logic

In the early iterations of the Ace Rentals API, authorization checks were implemented directly within route handlers. Each route was responsible for independently verifying whether a user was authenticated and whether they owned the target resource.

While this approach worked functionally, it resulted in repeated authorization logic scattered across the codebase. Any route that allowed deletion or modification had to manually include the same ownership check, increasing the risk of inconsistency and oversight as the system evolved.

The turning point came when I added a new endpoint and realized — almost as an afterthought — that I needed to repeat the same ownership check yet again. For a moment, it wasn’t clear whether I had already enforced it elsewhere or had simply assumed it was covered. Nothing broke, but that uncertainty itself was the problem. The system still worked, yet it was becoming increasingly difficult to trust.

At this point, I had to work within a few clear constraints. The API was already functional, so the solution needed to avoid breaking existing routes or changing how clients interacted with the system. Rewriting large parts of the application or introducing additional services would have added complexity without solving the underlying problem. Given these constraints, the focus was on improving how authorization rules were structured within the existing Express setup rather than redesigning the system entirely.

Observing the Problem in Code

A closer examination of the code structure reveals that both deletion routes perform identical ownership verification logic: the resource is fetched, the creator’s identifier is compared against the logged-in user’s identifier, a forbidden response is returned if the check fails, and execution proceeds only if authorization succeeds.

// Delete Listing Route
router.delete('/listings/:id', (req, res) => {
  Listing.findById(req.params.id, (err, listing) => {
    // ⚠️ SECURITY CHECK - Must be manually added to every route
    if (listing.creator.toString() !== req.user._id.toString()) {
      return res.status(403).send("Unauthorized");
    }
    // ⚠️ Problem: If I forget this check, users can delete ANY listing
    listing.deleteOne();
    res.redirect('/listings');
  });
});

// Delete Review Route - IDENTICAL LOGIC (Copy-Pasted Security Check)
router.delete('/reviews/:id', (req, res) => {
  Review.findById(req.params.id, (err, review) => {
    // ⚠️ SAME SECURITY CHECK - Duplicated code, different variable names
    if (review.author.toString() !== req.user._id.toString()) {
      return res.status(403).send("Unauthorized");
    }
    // ⚠️ Problem: If I forget this check, users can delete ANY review
    review.deleteOne();
    res.redirect('/');
  });
});

Although the routes operate on different resources, the authorization logic is effectively the same. The only variation lies in the property names (listing.creator versus review.author). This pattern led to authorization checks being duplicated across multiple routes, requiring developers to remember to re-implement the same logic each time a new endpoint was added.

The risk was subtle but significant: forgetting this check even once could allow a user to delete a resource they did not own, introducing a potential security vulnerability.

Another observed challenge was that someone examining the code structure might not readily discern that reviews belong to listings. That relationship existed primarily in the database schema; the API structure did not explicitly reveal it.

Structural Limitations in the API Design

Another limitation emerged from the API structure itself. From the routing design alone, it was not immediately clear that reviews belonged to listings. This relationship was primarily expressed at the database level rather than being reflected explicitly in the API’s URL structure, reducing the self-documenting nature of the interface.

Identified Issues

Based on these observations, two core issues were identified:

• Duplicated authorization logic, increasing maintenance effort and the likelihood of inconsistent updates.
• Non-systematic authorization coverage, where security relied on manual repetition rather than structural enforcement, increasing the risk of missed checks.

To make the scattered nature of my authorization logic more apparent, refer to the visual representation below:

Key Learning: Repetition in code could be a probable signal that something is structurally wrong. When one solves the same problem multiple times, it may be time to rethink the design approach.

---

Finding the Root Cause: Structured Problem-Solving

Diagnosing Structural Gaps Using MECE Analysis

I recognized that my approach lacked consistency. Routes were being named around actions rather than organized around resources, which led to fragmented structure and repeated logic. To address this, I applied a framework I learned after graduating from the McKinsey Forward Program: MECE (Mutually Exclusive, Collectively Exhaustive) thinking.

Viewed through this lens, the authorization issue became clear. The logic was not mutually exclusive, as the same ownership checks were duplicated across multiple routes. It was also not collectively exhaustive, because there was no systematic mechanism to guarantee that every route was protected.

As a result, each new feature introduced unnecessary risk—every change relied on manual discipline and the assumption that no security check would be overlooked. This lack of structural enforcement made the system fragile and difficult to scale

To clarify the structural issues, the MECE analysis below visually highlights the flaws in the overall design:

Evaluating Architectural Options with a Prioritization Matrix

The MECE analysis revealed what was wrong with my approach, but I still had multiple potential solutions. I needed a structured way to choose the best long-term design. I used the Prioritization Matrix to evaluate each approach against key criteria and identify the optimal solution.

Each option was evaluated using two primary criteria: code reusability and long-term maintainability.

To evaluate possible solutions, I referred to the following prioritization matrix to clearly compare their respective strengths and weaknesses:

Breaking down each option, the table below summarizes how each architectural approach performs across the two evaluation criteria, along with the key trade-offs involved.

Architecture Approach	Code Reusability	Maintainability	Key Trade-offs
Action-Based + Scattered	Low	Low	High burden, easy to miss, no reuse
Action-Based + Centralized	Low	High	Better maintenance, but verb-heavy
Resource-Based + Scattered	High	Low	Clean URLs, but inconsistent security
Resource-Based + Centralized	High	High	✅ Clean URLs, reusable, consistent

The prioritization matrix made the path forward clear. Of the four quadrants analyzed, only resource-based routes with centralized middleware delivered both high code reusability and high maintainability. This analysis eliminated guesswork—the data pointed to one optimal solution. Now I needed to transform this strategic choice into actionable implementation steps.

Translating Analysis into Executable Goals

After identifying the root cause and selecting the architectural direction, the remaining challenge was execution. I realized that without clear boundaries, even a well-reasoned refactor could easily expand beyond its original intent. Defining SMART goals helped me translate analysis into disciplined action and, more importantly, taught me how to control scope during implementation.

SMART Criteria	Implementation Target	Implementation Necessity	Status
Specific	Centralize authorization into a single middleware	A single control point was necessary to avoid relying on memory when adding or modifying routes	✅
Measurable	Remove duplicated ownership checks from all protected routes	Provided a concrete way to verify that the refactor actually reduced authorization risk	✅
Achievable	Use existing Express middleware patterns	Kept the solution practical and understandable without introducing unnecessary complexity	✅
Relevant	Improve security and reduce authorization-related bugs	Directly addressed the core issue identified during earlier analysis	✅
Time-Bound	Complete the refactor within two weeks	Prevented scope creep and enforced focused, incremental changes	✅

What I learned through this step was that SMART goals are less about planning and more about restraint. Explicitly stating why each constraint existed made it easier to stay focused during implementation and avoid turning a targeted refactor into a broader redesign.

---

Implementation Impact

This implementation transformed authorization from a repeated, route-level responsibility into a centralized, system-level guarantee. Previously, authorization checks were embedded directly within individual route handlers, requiring manual enforcement in every endpoint. Guided by MECE analysis to identify authorization as a cross-cutting concern, validated through a prioritization matrix as the most maintainable approach, and executed using SMART goals, the refactor consolidated ownership checks into dedicated middleware applied consistently across protected Express routes. Middleware was the appropriate abstraction because authorization is orthogonal to business logic and must execute before any state-changing operation. As a result, duplicated logic was eliminated, the risk of inconsistent or missing authorization enforcement was reduced, route handlers remained focused on business logic, and the system became easier to extend, safer to modify, and more predictable as the codebase scales. This implementation also reinforced the importance of addressing structural problems before writing code, demonstrating how upfront architectural decisions can reduce long-term complexity more effectively than incremental fixes.

The Redesign: Action-Based to Resource-Based

The restructured approach allows HTTP methods to carry the action while URLs carry the resource. On perusal of the table below, one can observe how this structure potentially makes the API more predictable and self-documenting.

Operation	Before (Action-Oriented Endpoints)	After (RESTful Resources)	Why This Matters
Create listing	POST /create-listing	POST /listings	HTTP method implies action
View listing	GET /get-listing/:id	GET /listings/:id	Cleaner, standard
Update	PUT /update-listing/:id	PUT /listings/:id	Resource-scoped
Delete listing	DELETE /delete-listing/:id	DELETE /listings/:id	Consistent
Create review	POST /create-review	POST /listings/:id/reviews	Shows ownership
Delete review	DELETE /delete-review/:id	DELETE /listings/:id/reviews/:rid	Clear hierarchy

The diagram below illustrates the transition from route-level authorization checks to a centralized middleware approach:

Building the Solution: Centralized Authorization

Instead of writing the ownership check in every route, I created one reusable middleware function. This function encapsulates all the authorization logic in a single place. It uses Express's middleware pattern where next() passes control to the next handler only if authorization succeeds:

const isOwner = async (req, res, next) => {
  const listing = await Listing.findById(req.params.id);
  if (!listing.author.equals(req.user._id)) {
    req.flash('error', 'You cannot modify this listing');
    return res.redirect('/listings');
  }
  next();
};

This middleware is intentionally single-purpose: it verifies whether the current user owns the listing. The listing.author.equals() method safely compares MongoDB ObjectIds to avoid false matches. If the check fails, an error is flashed and the request is stopped before any data is modified. If it passes, next() forwards the request to the route handler.

Then I applied this single middleware to all protected routes, chaining it with authentication:

router.put('/:id', isLoggedIn, isOwner, updateListing);
router.delete('/:id', isLoggedIn, isOwner, deleteListing);
router.delete('/:id/reviews/:rid', isLoggedIn, isOwner, deleteReview);

Read these routes from left to right—they form a pipeline. First isLoggedIn verifies the user has a valid session, then isOwner verifies ownership, and finally the business logic executes. The transformation is profound: the authorization check exists in exactly one place. If I need to add logging, change the error message, or modify the authorization logic, I change it once and it applies everywhere. New features automatically inherit the same security pattern—no chance of forgetting.

While the middleware code itself is straightforward, understanding how requests flow through this pipeline reveals the true power of this architectural pattern. The sequential execution of authentication, authorization, and business logic creates a clear separation of concerns that makes the system both more secure and more maintainable.

The following visual summarizes the measurable improvements in consistency, maintainability, and scalability after implementing centralized authorization: