✅ Flat route structure

[williamgcampbell]

This is one part question, one part suggestion. I've never thought much about the nested route structure chosen by this repo until I tried to use an express-like flat structure andnwas met with an error from express-zod-api. Why commit so heavily to preventing users of the framework from using a flat structure? As the path gets more complex the nesting gets quite verbose. For example:

const routing: Routing = {
  '/v1/foo/bar/baz': endpoint
}

vs

const routing: Routing = {
  v1: {
    foo: {
      bar: {
        baz: endpoint
      }
    },
  },
};

There are certainly places where there can be a conflict between two routes when accepting a flat structured string but that can be handled quite easily by either accepting the first/last or rejecting altogether. I'm curious if there were any other considerations for the enforcement of a nested structure. Personally, I've been more inclined to write a converter from a structure like the one below, to the nested route structure in my projects.

export const routes: FlatRoutes = {
    'get /v1/books/:bookId': getBooksEndpoint,
    'delete /v1/books/:bookId': deleteBooksEndpoint
};

[RobinTail]

Object-based structure is for organizing and constraints, @williamgcampbell

1. You keep nested segments inside the parent one, so that, for example, operations over certain entity are declared nearby. It's not "foo/bar" in real life scenarios.

2. You avoid manual input mistakes by defining the parent segment once. You don't repeat yourself, which is also a good practice. Count "v1" and "books" in your example. You can make a typo. Also, when you decide to move to "v2" all deprecated routes would be inside the single object.

But your suggestion on having alternative way to establish routing is interesting. I'll take a look on that.

[williamgcampbell]

Thanks! And yes, that all makes sense. Some of this comes from personal preference and size of the project, but I'll add that I've found the following to to be the case as I've used it more.

• Code search-ability is pretty difficult with nesting. It's such a small quality of life improvement but really makes a difference when navigating any code that you aren't very familiar with. Keeping the definition of the route close to the way we display the path to humans in logs/traces or HTTP clients is important IMO.
• Eliminating repetition is good, but routes are one of the few exceptions that I think should be more declarative, so that it's easier to quickly get a sense of the endpoints available. As an example, take the extension of the Book API example below, you can in an instant get a sense of the endpoints available in the flat structure but your eyes need to navigate the path a bit more with nesting.
• With regard to catching typos, I would say that routes are going to be a services primary output and will be one of the most scrutinized aspects when it comes to testing and integration, so a typo will almost certainly be the first thing noticed.
• As important as duplication is to some, line count is important to others. A file with 20 routes that could otherwise be 20 lines of code can easily explode into 4x that for routes with multiple paths. Splitting the file structure into logical nested files can help but it's hard to ignore a flat structure when that's the default in express.

{ 
  'get /v1/books/:bookId': getBooksEndpoint,
  'delete /v1/books/:bookId': deleteBooksEndpoint
  'patch /v1/books/:bookId': deleteBooksEndpoint
  'put /v1/books/:bookId': deleteBooksEndpoint

  'post /v1/library/:libraryId/checkout/:bookId': checkoutBook
}


vs


{
  'v1': {
    'library': {
      ':libraryId': {
        'checkout': {
          ':bookId' {
             '': new DependsOnMethod({
               post: checkoutBook,
             }),
           }
        }
      }
    },
    'books': {
      ':bookId': {
        '': new DependsOnMethod({
          get: getBooksEndpoint,
          delete: deleteBooksEndpoint
          patch: patchBooksEndpoint
          put: putBooksEndpoint
        }),
      }
    },
  },
}

[RobinTail]

#2623

[RobinTail]

🚀 v23.4.0, @williamgcampbell
Thank you for the contribution!

[williamgcampbell]

That was fast, thanks!