Ky: Document `prefixUrl` reasonings

[sindresorhus]

See https://github.com/sindresorhus/ky/issues/66#issuecomment-484949029

[KubaJastrz]

While I understand issues in the linked comment, I usually search for endpoint urls starting with leading slash, because that's how they are defined on the project's backend and in swagger documentation.

To keep it consistent while using ky, I'm using following wrapper (simplified version):

const api = ky.create({
    prefixUrl: process.env.BASE_URL,
})

function request(method, url, options) {
    const requestUrl = url.startsWith('/') ? url.slice(1) : url;
    return api[method](requestUrl, options).json();
}

Now I can easily use this in my code:

const someData = await request('get', '/endpoint/path');

[sholladay]

The reason your backend URLs start with a slash is because they are origin-relative, meaning they specify the full path, as opposed to page-relative, meaning they specify only a partial path.

It's a meaningful difference, because fetch('foo') will request a completely different resource than fetch('/foo') (unless you are at the root of the origin). The former is page-relative, the latter is origin-relative.

I generally think it would be wrong of ky to interpret the input argument differently than fetch does, given that the URL resolution that fetch does is widely implemented across the web stack. So I like that our current implementation forces you to exclude the slash when using prefixUrl, because it makes it clear that input is a partial path in that case, and keeps us consistent with the rest of the web.

That said, I'm personally open to making the slash optional just to be pragmatic, so long as there's some consensus about it.

[KubaJastrz]

Thank you for your input. It makes perfect sense to be as close to the web spec as possible. XMLHttpRequest and fetch resolve relative and absolute paths in the same way.

That said, for users coming from packages like axios this might be confusing since you can create api instance with url containing pathname and single requests resolve full url based on that.

const api = axios.create({
  baseURL: 'https://example.com/api'
})

api.get('/foo') // => https://example.com/api/foo

[sholladay]

I am in favor of having a baseUrl option that is mutually exclusive with prefixUrl, which would behave the same way a <base> tag does in HTML.

IIRC, Sindre preferred to have only one of these for simplicity and we went with prefixUrl. Still probably worth discussing if you think that would be very useful to you.