Ga naar hoofdinhoud

cnFetch

fetch with Nextcloud's URL prefix and headers applied. The library-owned HTTP client named by ADR-071 Decision 1.

Raw fetch() with a hand-set requesttoken in app code is review-blocking once shipped. Use this instead.

import { cnFetch } from '@conduction/nextcloud-vue'

const response = await cnFetch('/apps/openregister/api/objects/myreg/myschema', {
    query: { limit: 20, _search: 'invoice' },
})

Signature​

cnFetch(url, options?) => Promise<Response>
ParameterTypeDescription
urlstringApp-absolute path, e.g. /apps/openregister/api/objects.
optionsobjectStandard fetch options, plus the two below.
options.queryobjectSerialised via buildQueryString and appended to the URL.
options.headerOptionsobject | string | nullPassed through to buildHeaders (content type, organisation UUID, translation target).

Returns the raw Response.

What it does for you​

  • prefixUrl — Nextcloud may be served with or without /index.php. An API call must use the same prefix as the page, or the request is rejected.
  • buildHeaders — the single blessed CSRF idiom (requesttoken: OC.requestToken), plus Content-Type, the OpenRegister organisation header and the translation-target header.
  • buildQueryString — consistent query serialisation.

It does NOT throw on a non-2xx​

This is deliberate: a probe that legitimately expects a 404 can read response.status without exception handling.

const response = await cnFetch('/apps/myapp/api/thing/maybe-missing')
if (response.status === 404) {
    // a normal outcome here, not an error
}

For the common case — parse JSON, throw on failure — use cnFetchJson.

Overriding a header​

Caller-supplied headers win, so a one-off Accept does not require dropping to raw fetch. That matters: bypassing the helper is how apps end up hand-setting requesttoken again.

await cnFetch('/apps/myapp/api/export', { headers: { Accept: 'text/csv' } })

See also​

  • cnFetchJson — JSON parsing plus error normalisation
  • CnHttpError — the error cnFetchJson throws
  • buildHeaders, buildQueryString