Docs: Syntax for routing rules doesn't seem to be documented anywhere

[johnmreynolds]

What were you searching in the docs?

I've been trying to find any documentation on how the routing rules work, but even in the API reference it's just documented as being a 'str'.

https://docs.powertools.aws.dev/lambda/python/latest/api/event_handler/index.html#aws_lambda_powertools.event_handler.ApiGatewayResolver.route

From the tutorials and source code, it looks like this should be a regex, but there is no indication of what regex syntax this follows, or how variable capture works with decorated functions.

For example, the tutorials include things like @app.get("/subscriptions/") which seems to be a curious syntax, and I can't find any documentation on this. Also, it doesn't seem to work for subfolders which is weird.

Is this related to an existing documentation section?

https://docs.powertools.aws.dev/lambda/python/latest/api/event_handler/index.html#aws_lambda_powertools.event_handler.ApiGatewayResolver.route

How can we improve?

Document how the routing rules work somewhere.

Got a suggestion in mind?

No response

Acknowledgment

• I understand the final update might be different from my proposed suggestion, or refused.

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[leandrodamascena]

Hello @johnmreynolds! Thanks for bringing up this important point about the documentation. If it was difficult for you to find clear information in our documentation, it may be difficult for others too and we need to fix it.

Let me split this issue to make it easier to define the next steps.

1 - Method signature:
In the informed method signature, the rule parameter is str because it is a string where in most of cases developers can add static or dynamic paths.

• static path: @app.get("/powertools")
• dynamic path: @app.get("/powertools/<customer_id>")

In some special cases, developers can add a regex to catch all routes, or create more advanced dynamic routes

• catch all: @app.get(".+")
• advanced dynamic route: @app.get("/accounts/(?P<account_id>.+)")

I think the confusion here is that even the signature method is a string, behind the hood we compile a regex to make it more flexible. In this method we have some regex examples, but I agree that is hard to find.

2 - Subfolders:

For example, the tutorials include things like @app.get("/subscriptions/") which seems to be a curious syntax, and I can't find any documentation on this. Also, it doesn't seem to work for subfolders which is weird.

Can you please elaborate a little more on that? I didn't understand the point of subfolders. We support a path like /powertools/test/hello, is that what you mean?

3 - Next steps:
Do you have any suggestions that we can add to our documentation to make it clearer? Maybe adding a specific section on regex and some examples? Adding docstring to route method to explain parameters?
If you have any ideas or even want to submit a PR to improve our documentation please do so, we love it when we can improve our documentation to make it easier for us to communicate with our customers.

I'm adding the "Pending customer" status because we want to hear from you before proceeding.

Thanks

[johnmreynolds]

Thanks.

On the topic of subfolders, github mangled my comment which included angle brackets, so my example made no sense.

What I meant is like in your example:
@app.get("/powertools/<customer_id>")

where customer_id captures the path, it seems not to work if what would be captured for customer_id contains a slash, so is a subfolder of /powertools/. This is probably sensible, and I think is covered by the examples in the source you pointed at (implied by the word boundary match) but I was just noting I couldn't find this documented anywhere.

On how to improve the documentation, I think yes it could do with small additions of:

1. just a short section on what can be passed to the rule, which I think can be one of a) regex, b) a dynamic path with angle brackets or c) a static path (which is a special case of regex).

2. How dynamic path matching works (if I'm reading the comment you linked correctly it's just a word boundary match).

3. How the captured parts of the path get passed to the decorated function. From the example it looks clear this happens as an extra parameter for dynamic paths, but I couldn't see any documentation that this also happens for regex captures (I'm assuming it does - I've just not tested it).

[leandrodamascena]

Hello @johnmreynolds! Thanks for adding your ideas to improve the documentation.

1 - just a short section on what can be passed to the rule, which I think can be one of a) regex, b) a dynamic path with angle brackets or c) a static path (which is a special case of regex).

Except the regex case, where we don't have a detailed section, the other things like dynamic and static path we already have in our documentation. However, I think that since this is split into multiple sections of our documentation, it might be good to create a new section called "Working with Rules" or something similar to make it clearer and explain these gaps.

2 - How dynamic path matching works (if I'm reading the comment you linked correctly it's just a word boundary match).

It can be covered in this new section.

3 - How the captured parts of the path get passed to the decorated function. From the example it looks clear this happens as an extra parameter for dynamic paths, but I couldn't see any documentation that this also happens for regex captures (I'm assuming it does - I've just not tested it).

Same for the previous question.

Do you want to send a PR so we can work together? It would be great to have your contribution to improve the documentation of a widely used utility in Powertools. This PR can be a draft, in case you don't have all the information and I'll help you with whatever you need.

Thanks

[leandrodamascena]

Adding backlog status until we start working on it.

[dmarra]

I want to share my experience (originally from discussion #2976 ):

In the documentation, it is stated in the section about catch-all routes the following:

We choose the most explicit registered route that matches an incoming event.

I understood this to mean that in the case where a more specific match is found, that it will pick the more explicit match over the other. For instance:

@app.get(".+")
def catch_all():
    pass

@app.get("/my/resource/<resource_id>")
def more_explicit():
    pass

In this case, I would think from the docs that a request to /my/resource/12345 would invoke more_explicit, but in practice I see the opposite happen (catch_all is invoked for everything). In fact, it does this no matter what order the methods are added in.

This seems like a bug honestly. But, I can see the difficulty in determining which rules are more explicit than others. How exactly does one determine that reliably from a regex?

I suggest adding the ability to explicitly define the priority of a rule against others. Something like:

@app.get(".+", priority=2)
def catch_all():
    pass

@app.get("/my/resource/<resource_id>", priority=1)
def more_explicit():
    pass

Perhaps with the following behavior:

1. priority is in ascending order (with 0 being highest for instance)
2. rules of equal priority are analyzed in the order they appear in the code
3. not setting a priority defaults to the lowest possible priority (in the example above, not setting priority in a new rule would effectively make it priority=3

Basically, let the user determine which is more important than the other instead of trying to infer it. This way, at least the user has a way out if there is a bug in the ordering