ky icon indicating copy to clipboard operation
ky copied to clipboard

Add baseUrl option, rename prefix, and allow leading slashes in input

Open sholladay opened this issue 1 year ago • 20 comments

Closes #291

This PR aims to improve the flexibility of input URLs and options for resolving them prior to the request.

  • The prefixUrl option is renamed to prefix to avoid implying that it behaves as a URL with resolution semantics
    • As before, it is prepended to input before any other processing takes place, and it can be a path or full URL with host, if needed.
    • Its primary use case is now to force requests to use a particular path, such as /api, even when input contains a leading slash. In most cases, the new baseUrl option should be used instead for improved flexibility.
  • A new baseUrl option is added which performs URL resolution on the combined prefix + input
    • When this option is used, input (including any prefix) is resolved against the baseUrl to determine the final request URL, according to standard URL resolution rules.
    • Using baseUrl is similar to using the HTML <base> tag or changing the window.location before making the request (except it only applies to Ky). As such, the presence of a trailing slash in the baseUrl and the presence of a leading slash in input (or prefix, if applicable) can affect the final request URL. For example, if input contains a leading slash, it will bypass the path part of the baseUrl, unlike what would happen if the base URL were provided as a prefix. The host will also be bypassed if the input is an absolute URL. This flexibility is what makes baseUrl useful (see https://github.com/sindresorhus/ky/issues/291).
    • baseUrl can be a path or full URL and it will be resolved against document.baseURI, if necessary.
  • baseUrl and prefix can be used independently or together, they are optional and not mutually exclusive.
  • input can now be provided with or without a leading slash, regardless of which options are used. Previously, using a leading slash in input was not allowed to be combined with a prefix URL. Now, slashes are allowed and automatically normalized so that there will always be a single slash between prefix and input, whether or not prefix ends with a slash or input begins with a slash. However, baseUrl is sensitive to slashes, as explained above. See the table below for examples.

Typical usage

baseUrl prefix input Request URL
'/api/' '' 'users' /api/users
'http://foo.com/api/' '' 'users' http://foo.com/api/users
'http://foo.com/api/' '' 'http://bar.com/other' http://bar.com/other
'' '/api' '/users' /api/users
'' 'http://foo.com/api' '/users' http://foo.com/api/users

Slashes: prefix joins, baseUrl resolves

baseUrl prefix input Request URL
'' 'http://foo.com/api/v2' 'users' http://foo.com/api/v2/users
'' 'http://foo.com/api/v2' '/users' http://foo.com/api/v2/users
'' 'http://foo.com/api/v2/' 'users' http://foo.com/api/v2/users
'' 'http://foo.com/api/v2/' '/users' http://foo.com/api/v2/users
'http://foo.com/api/v2' '' 'users' http://foo.com/api/users
'http://foo.com/api/v2' '' '/users' http://foo.com/users
'http://foo.com/api/v2/' '' 'users' http://foo.com/api/v2/users
'http://foo.com/api/v2/' '' '/users' http://foo.com/users

sholladay avatar Jul 04 '24 09:07 sholladay