search

belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
24 stars 4 forks source link

URLs in identifiers ? #117

Closed barthanssens closed 1 year ago

barthanssens commented 1 year ago

See also https://www.belgif.be/specification/rest/api-guide/#rule-id-choice

Ideas on coding URL/URI in identifiers ?

Use case: BEST-address, we get IDs from the Regions who happen to be URIs/URLs, so the ID in a GET request may look like

https://example.com/best/v2/addresses/https://data.vlaanderen.be/id/adres/1132760/2015-07-15T17:51:56.940

Which is ugly to process in high-level frameworks (one has to do some processing at a lower level to make sure the parts after : aren't server ports and / are not paths on the server)

URLencoding could help somewhat:

../addresses/https%3A%2F%2Fdata.vlaanderen.be%2Fid%2Fadres%2F1132760%2F2015-07-15T17%3A51%3A56.940

But it is likely to break when a proxy or API gateway or firewall is sitting between the end application and a client, since they often decode + normalize and/or reject this to avoid path traversal attacks..

Other option would be to have it as a query parameter /?id=http... but that is likely to be decoded / break as well...

Yet another option would be to use _ for the problematic characters, but that's a custom solution (and prohibits the use of that character in said ID...)

pvdbosch commented 1 year ago

Hi @barthanssens, we already had quite some discussion about pros and cons of choosing to use URIs as identifiers:

As the type of identifier is already determined to be a URI in this case, they should be passed as URL-encoded strings when used as query or path parameter IMO. Colons aren't mandatory to escape when they're part of a parameter in an absolute URI, but slashes are.

URL-encoded values should be less prone to being blocked than unencoded ones, and encoding or decoding of parameters is usually automatically done by REST frameworks or libraries. I don't know if an API Gateway needs to be tweaked, but proxies or firewalls should generally be able to pass URI-encoded parameters, e.g. for OAuth2 redirection.

barthanssens commented 1 year ago

ok thanks, so urlencoding is the way to go

just for info, some (reverse) proxies do need some tweaking (see e.g. https://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes)