refactor(backend): return 404 instead 400 status when postcode fails to resolve to location

Author: mrzzy

backend/api.d.ts

@@ -274,6 +274,15 @@ export interface paths {
             "application/json": components["schemas"]["Error"];
           };
         };
+        /** @description No location found for one or more addresses. */
+        404: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["Error"];
+          };
+        };
         /** @description Internal server error */
         500: {
           headers: {
@@ -323,7 +332,7 @@ export interface paths {
             "application/json": components["schemas"]["Location"];
           };
         };
-        /** @description Invalid postcode. */
+        /** @description Invalid request parameters. */
         400: {
           headers: {
             [name: string]: unknown;
@@ -332,6 +341,15 @@ export interface paths {
             "application/json": components["schemas"]["Error"];
           };
         };
+        /** @description No Location for postcode found. */
+        404: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": components["schemas"]["Error"];
+          };
+        };
         /** @description Internal server error */
         500: {
           headers: {

backend/error.ts

@@ -27,3 +27,27 @@ export class ValidationError extends Error {
     this.status = 400;
   }
 }
+
+/**
+ * Represents an error that occurs when a requested resource is not found.
+ * Extends the standard JavaScript `Error` class with an additional `status` property, indicating
+ * an HTTP status code for "Not Found".
+ *
+ * @property {number} status - HTTP status code associated with the error, set to 404 (Not Found).
+ *
+ * @constructor
+ * @param {string} message - A descriptive message explaining the missing resource error.
+ *
+ * @example
+ * throw new NotFoundError("Resource not found");
+ */
+export class NotFoundError extends Error {
+  status: number;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "NotFoundError";
+    // not found status code
+    this.status = 404;
+  }
+}

backend/index.ts

@@ -10,6 +10,7 @@ import { Request, Response } from "express";
 import * as OpenApiValidator from "express-openapi-validator";
 import { ROUTING_API, RoutingSvc } from "./services/routing";
 import { paths } from "./api";
+import { ValidationError } from "./error";
 
 type GeoLocation = {
   latitude: number;
@@ -49,37 +50,31 @@ app.post("/route", async (req: Request, res: Response) => {
   const r =
     req.body as paths["/route"]["post"]["requestBody"]["content"]["application/json"];
 
-  try {
-    let srcLocation: GeoLocation;
-    let destLocation: GeoLocation;
+  let srcLocation: GeoLocation;
+  let destLocation: GeoLocation;
 
-    if (r.src.kind === "address") {
-      const postcode = r.src.address?.postcode?.trim();
-      if (!postcode) {
-        throw new Error("Source address must include a postcode.");
-      }
-      srcLocation = await routing_service.geolookup(postcode);
-    } else {
-      srcLocation = r.src.location!;
+  if (r.src.kind === "address") {
+    const postcode = r.src.address?.postcode?.trim();
+    if (!postcode) {
+      throw new ValidationError("Source address must include a postcode.");
     }
+    srcLocation = await routing_service.geolookup(postcode);
+  } else {
+    srcLocation = r.src.location!;
+  }
 
-    if (r.dest.kind === "address") {
-      const postcode = r.dest.address?.postcode?.trim();
-      if (!postcode) {
-        throw new Error("Destination address must include a postcode.");
-      }
-      destLocation = await routing_service.geolookup(postcode);
-    } else {
-      destLocation = r.dest.location!;
+  if (r.dest.kind === "address") {
+    const postcode = r.dest.address?.postcode?.trim();
+    if (!postcode) {
+      throw new ValidationError("Destination address must include a postcode.");
     }
-
-    const routes = await routing_service.route(srcLocation, destLocation);
-    res.json({ routes });
-  } catch (error) {
-    console.error(error);
-    const err = error as Error;
-    res.status(500).json({ message: err.message });
+    destLocation = await routing_service.geolookup(postcode);
+  } else {
+    destLocation = r.dest.location!;
   }
+
+  const routes = await routing_service.route(srcLocation, destLocation);
+  res.json({ routes });
 });
 
 app.get("/geocode/:postcode", async (req: Request, res: Response) => {

backend/services/routing.ts

@@ -9,7 +9,7 @@ import * as path from "path";
 import csv from "csv-parser";
 import { components, paths } from "../api";
 import { CongestionSvc } from "./congestion";
-import { ValidationError } from "../error";
+import { NotFoundError } from "../error";
 
 // OSRMText instructions
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -54,7 +54,7 @@ export class RoutingSvc {
     const location = this.postcodeLookup.get(normalizedPostcode);
 
     if (!location) {
-      throw new ValidationError(`No location found for postcode: ${postcode}`);
+      throw new NotFoundError(`No location found for postcode: ${postcode}`);
     }
 
     return location;

lib/api_codegen.dart

@@ -1,4 +1,4 @@
-// Openapi Generator last run: : 2024-10-31T22:41:50.903620
+// Openapi Generator last run: : 2024-10-31T22:55:43.313382
 import 'package:openapi_generator_annotations/openapi_generator_annotations.dart';
 
 @Openapi(

packages/flowmotion_api/.openapi-generator/FILES

@@ -43,4 +43,3 @@ lib/src/model/route_post_request_dest.dart
 lib/src/model/route_post_request_src.dart
 lib/src/serializers.dart
 pubspec.yaml
-test/geocoding_api_test.dart

schema/flowmotion_api.yaml

@@ -305,6 +305,12 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+        "404":
+          description: No location found for one or more addresses.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
         "500":
           description: Internal server error
           content:
@@ -332,7 +338,13 @@ paths:
               schema:
                 $ref: "#/components/schemas/Location"
         "400":
-          description: Invalid postcode.
+          description: Invalid request parameters.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: No Location for postcode found.
           content:
             application/json:
               schema: