136: make custom method paths follow a sub-resource like structure

[toumorokoshi]

The original motivation for this discussion starts with https://cloud-native.slack.com/archives/C04TX46UCTV/p1751055711107579. Inlined:

Running into a problem with soft delete w/ AWS API Gateway.
Unable to create resource at path '/instances/{instance_id}/encryption-keys/key-encryption-keys/{id}:undelete': Resource's path part only allow a-zA-Z0-9._-: or a valid greedy path variable and curly braces at the beginning and the end.
I think it expects "greedy path variables" like {id}in that example to not share a path with the :undelete part. Suggestions?

It's probably not worth modifying the API guidance on behalf of one specific API gateway implementation. However, the existing structure does include inconsistencies that I think are problematic from a design standpoint, as well: {id}:customMethodName looks kind of like a resource, so pattern matching frameworks which work off of path match delimiters may not be able to properly parse the custom method out (without custom logic).

Some alternatives:

1. raised by @thegagne: /{id}/actions/undelete - effectively create a specific subresource for custom methods.
2. {id}/:undelete - a subcollection that is prefixed with a colon is a custom method.

I think (1) comes with a couple disadvantages:

• the slight disadvantage that "actions" is a now a reserved namespace.
• the fact that it looks like actions is a subresource, and there will be additional complexity in clients to support this specific pattern.

(2) does not come with the the first disadvantage. There will be some custom handling needed for 2, but this is no more complex than existing clients which have to parse out the custom method.

Either way, I think it would be best to adjust this pattern to help support less flexible path parses and gateways.

[toumorokoshi]

Looks like Kubernetes HTTPRoute for their HTTPPath supports exact, a prefix, or a regex. So likely this pattern would be bucketed in the regex due to variable resource ids, or delegate the path matching to the service.

[toumorokoshi]

This might be better off as a discussion - it's a long-lived topic that would have significant changes, if we chose to adopt it.

[thegagne]

The issue with the /:custom-method approach is it might look too much like path-to-regexp style parameters.

See https://github.com/pillarjs/path-to-regexp

And for example: https://zuplo.com/docs/articles/routing

I'm not certain this overlap is a problem, but it's prior work to consider as we look for a pattern.

[toumorokoshi]

The issue with the /:custom-method approach is it might look too much like path-to-regexp style parameters.

Thanks for the examples! I think rails is another one: https://guides.rubyonrails.org/routing.html.

I think almost any approach comes with some syntax or approach that would make route matching difficult:

• there's only so many characters that are allowed in HTTP paths without escaping.
• other options, like mounting in custom methods as a subpath, breaks some ability to infer the purpose of the path (although singletons to some extent break that as well).

[toumorokoshi]

The discussion during the aep-weekly was that, generally, it's impossible to find something that fits with every API framework. Perhaps a pathing decision could be based on that data, but the rationale to change this approach would have to likely be beyond simple integration in all known frameworks.