shlink/docs/adr/2023-01-06-support-any-http-method-in-short-urls.md

Support any HTTP method in short URLs

• Status: Accepted
• Date: 2023-01-06

Context and problem statement

There has been a report that Shlink behaves as if a short URL was not found when the request HTTP method is not GET.

They want it to accept other methods so that they can do things like POSTing stuff that then gets "redirected" to the original URL.

This presents two main problems:

• Changing this could be considered a breaking change, in case someone is relying on this behavior (Shlink to only redirect on GET).

• Shlink currently supports two redirect statuses (301 and 302), which can be configured by the server admin.

  For historical reasons, a client might switch from the original method to GET when any of these is returned, not resulting in the desired behavior anyway.

  Instead, statuses 308 and 307 should be used.

Considered options

There's actually two problems to solve here. Some combinations are implicitly required:

• To support other HTTP methods in short URLs
  • Start supporting all HTTP methods.
  • Introduce a feature flag to allow users decide if they want to support all methods or just GET.
• To support other redirects statuses (308 and 307)
  • Switch to status 308 and 307 and stop using 301 and 302.
  • Allow users to configure which of the 4 status codes they want to use, insteadof just supporting 301 and 302.
  • Allow users to configure between two combinations: 301+308 and 302+307, using 301 or 302 for GET requests, and 308 or 307 for the rest.

Note

I asked on social networks, and these were the results (not too many answers though):

• https://fosstodon.org/@shlinkio/109626773392324128
• https://twitter.com/shlinkio/status/1610347091741507585

Decision outcome

Because of backwards compatibility, it feels like the bets option is allowing to configure between 301, 302, 308 and 307.

This has the benefit that we can keep existing behavior intact. Existing instances will continue working only on GET, with statuses 301 or 302.

Anyone who wants to opt-in, can switch to 308 or 307, and the short URLs will transparently work on other HTTP methods in that case.

The only drawback is that this difference in the behavior when 308 or 307 are configured needs to be documented, and explained in shlink-installer.

Pros and Cons of the Options

Start supporting all HTTP methods

• Good: Because the change in code is pretty simple.
• Bad: Because it would be potentially a breaking change for anyone trusting current behavior for anything.

Support HTTP methods via feature flag

• Good: because it would be safer for existing instances and opt-in for anyone interested in this change of behavior.
• Bad: Because it requires more changes in code.
• Bad: Because it requires a new config entry in the shlink-installer.

Switch to statuses 308 and 307

• Good: Because we keep supporting just two status codes.
• Bad: Because it requires applying mapping/transformation to convert old configurations.
• Bad: Because it requires changes in shlink-installer.

Allow users to configure between 301, 302, 308 and 307

• Good: Because it's fully backwards compatible with existing configs.
• Good: Because it would implicitly allow enabling all HTTP methods if 308 or 307 are selected, and keep only GET for 301 and 302, without the need for a separated feature flag.
• Bad: Because it requires dynamically supporting only GET or all methods, depending on the selected status.

Allow users to configure between 301+308 or 302+307

• Good: Because it would allow a more explicit redirects config, where values are not 301 and 302, but something like "permanent" and "temporary".
• Bad: Because it implicitly changes the behavior of existing instances, making them respond to redirects with a method other than GET, and with a status code other than the one they explicitly configured.
• Bad: because existing REDIRECT_STATUS_CODE env var might not make sense anymore, requiring a new one and logic to map from one to another.