ky
ky copied to clipboard
Add baseUrl option, rename prefix, and allow leading slashes in input
Closes #291
This PR aims to improve the flexibility of input URLs and options for resolving them prior to the request.
- The
prefixUrloption is renamed toprefixto avoid implying that it behaves as a URL with resolution semantics- As before, it is prepended to
inputbefore 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 wheninputcontains a leading slash. In most cases, the newbaseUrloption should be used instead for improved flexibility.
- As before, it is prepended to
- A new
baseUrloption is added which performs URL resolution on the combinedprefix+input- When this option is used,
input(including anyprefix) is resolved against thebaseUrlto determine the final request URL, according to standard URL resolution rules. - Using
baseUrlis similar to using the HTML<base>tag or changing thewindow.locationbefore making the request (except it only applies to Ky). As such, the presence of a trailing slash in thebaseUrland the presence of a leading slash ininput(orprefix, if applicable) can affect the final request URL. For example, ifinputcontains a leading slash, it will bypass the path part of thebaseUrl, unlike what would happen if the base URL were provided as aprefix. The host will also be bypassed if theinputis an absolute URL. This flexibility is what makesbaseUrluseful (see https://github.com/sindresorhus/ky/issues/291). baseUrlcan be a path or full URL and it will be resolved againstdocument.baseURI, if necessary.
- When this option is used,
baseUrlandprefixcan be used independently or together, they are optional and not mutually exclusive.inputcan now be provided with or without a leading slash, regardless of which options are used. Previously, using a leading slash ininputwas 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 betweenprefixandinput, whether or notprefixends with a slash orinputbegins with a slash. However,baseUrlis 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 |