Remove Simple Routing and Query Routing?

[evantahler]

Actionhero has 2 features aimed at making it easier to get up-and-running with new HTTP projects - simpleRouting and queryRouting. They are controlled via settings in config/servers/web.ts

// From config/servers/web.ts

// simple routing also adds an 'all' route which matches /api/:action for all actions.  All includes GET, POST, PUT and DELETE
simpleRouting: true,
// queryRouting allows an action to be defined via a URL param, ie: /api?action=:action
queryRouting: true,

However, these options (which are enabled by default in new projects) are confusing when considered alongside config/routes.ts. For example, if you make an action that you only want to appear as POST /api/users by adding it to your config/routes.ts, you will be surprised to see it also in GET and DELETE. Simple routing also makes it impossible to have a different action per HTTP verb at the same route, so it will need to be disabled in a majority of projects.

The negative side effect of removing Simple and Query Routing would be that you cannot view your actions on the web without first adding them to config/routes.ts.

What do you think about removing Simple Routing and Query Routing from Actionhero?

[evantahler]

There would be some extra work needed to create a routes file for demo.actionherojs.com - running Actionhero directly and having an "internal" routes file.

[evantahler]

Simple Routing (/api?action=:action) is one of the oldest features of Actionhero - at the time I was making an API for en embedded device that couldn't use REST (it's crazy, I know), so we needed a route-per-action... and only GETs were supported.

That said, now that we have a real router, I could have just handled this all in config/routes.ts, so for my use-case, removing query routing would be OK.

[gcoonrod]

If we were going to remove this I'd like to see it replaced with something in the Action template. Perhaps like:

class Status extends Action {
  constructor() {
    super();
    this.name = "status";
    this.description = "I will return some basic information about the API";
    this.path = "status";
    this.outputExample = {
      id: "192.168.2.11",
      actionheroVersion: "9.4.1",
      uptime: 10469,
    };
  }
}

Where path can be a template string similar to the current routes.ts implementation. I am not sure if this should augment what is in routes.ts or replace it.

[evantahler]

Fascinating! I'd love to hear more thoughts on how this interops with config/route.ts - if an action is listed in routes.ts... would it appear in 2 routes? Perhaps we also need verb here (POST, GET, etc)?

Note that there's a bit more complexity going in routes.ts - matching, param extraction, and wild-card matches too.

[evantahler]

Documentation for routes - https://www.actionherojs.com/tutorials/web-server#Routes

[gcoonrod]

I don't see a reason why an action can't have multiple routes. Having both the path and verb is necessary to replicate the behavior in rotues.ts but it does tie the actions more closely to HTTP when they were originally built to be transport agnostic. I like the idea of defining the path and verb on the action because it is a common pattern in the other api server projects (Express, Hapi, etc). But I don't know if that is actually what we want to do. Having all routing configuration in a single place does seem to have a lower cognitive overhead than sprinkling it throughout the actions.

Perhaps a better compromise is for the npx actionhero generate action command to amend the routes.ts config with a default route for each newly generated action. Not sure how complex this implementation would be though.

[evantahler]

Oh! I like the modification to npx actionhero generate action to add a route (and an option to skip it).

I think my goals are:

• a single place routes are defined (routes.ts)
• no surprises (simpleRoutes defines routes you can't see in routes.ts)
• keep the new developer experience easy (your actions can be viewed in the browser simply)

[mfvargo]

While I suppose a use case of having the same action available to multiple routes might be a valid one I just ran into this and had to disable it. i was finding all my actions in swagger under get and not with their correct verbs according to routes.js. I can't really opine too hard on if this feature should be yanked or not. At a minimum it should mentioned a little louder in https://www.actionherojs.com/tutorials/web-server#Config%20Options

[mfvargo]

As an aside, in my case I have only one route to each action. I also am making the API self suggesting where when an object is retrieved, it presents to client with the set of API calls that can be used at that time depending on the role of the user and the state of the object in it's lifecycle. When I build that suggestion I have to search through routes to give the path to the action in the response. Being routes is organized as an array of objects with a top level node of the http verb it's not easy to search. I ended up creating a abstract base class for my actions that has a "verb" attribute so I can use that to search routes. It would be nice of you could index api.routes.routes with the action name and return the routes that match it.

[mfvargo]

It's not DRY at all because if the verb in the action does not match the one in routes I can't find the route to the action in api.routes.routes

[evantahler]

Linking your issue here actionhero/www.actionherojs.com#173

[evantahler]

@gcoonrod and I decided the path forward is:

1. remove simpleRoutes and queryRoutes - it's confusing and violates the principal of least surprise. Folks know about routes.ts and expect to use it.
2. To assist folks in getting the new actions working for the Web server, the npx generate action command will output a helpful hint like the following:

# npx generate action --name userEdit

To enable your new action in the webserver, please add `{path: '/userEdit', action: 'userEdit'}` to `src/config/routes.ts` under the HTTP method of your choice.

3. We will change the default src/config/routes.ts to have all HTTP verbs expanded by default and include the example actions like status.

[evantahler]

Work for this is in #1607