Avoid Fixed-Path Endpoint URLs That Match Dynamic/Parameterized Endpoint URLs

[mlm483]

When the URL for one endpoint could match another endpoint's URL (because a fixed path segment in one could be interpreted as a dynamic (i.e. parameterized) path segment in another), unexpected behavior can occur depending on the order in which paths are matched.

Example endpoints with this type of ambiguity in BrAPI 2.1 are the GET /observations/table and GET /observations/{observationDbId} endpoints.

Imagine a client makes a GET request to /observations/table.
If the BrAPI implementation checks the URL against the fixed path (/observations/table) first, everything works as intended. However, if it checks the URL against the dynamic path (/observations/{observationDbId}) first, that pattern will match and the implementation breaks in an unexpected way.

I believe some frameworks automatically try to match against fixed URLs first before trying to match against dynamic URLs, but some do not. I've seen this issue firsthand (though not with BrAPI) in Django, which checks URLs in the order in which they are listed by the developer.

I recommend avoiding this type of URL overlap as changes are made and new BrAPI modules (e.g. analytics) are developed, to make correctly implementing BrAPI easier for everyone who tries.

Totally agree! Also in the provided example the response is ObservationTableResponse. So a better endpoint would be:
/observationstable