WebRequest

webRequest is a thin wrapper over javascript fetch with some conveniences built in to it such as rearranging the includes in a response into a more expected array. It will automatically prefix the url with /v1/ unless it is given an absolute or site relative URL.

In general, rather than directly using webRequest, people will often use Loop, Content or Forms as they are more abstract and provide simpler API's for more specific tasks.

Simple usage

webRequest returns a javascript promise. If the request fails, it will throw. You are always expected to catch a failed webRequest and display it to the user. This is typically why Loop etc is recommended as much as possible, as it does that for you. The following examples use the Public API.

Simple GET request

Getting user #14 from the API at URL /v1/user/14:

import webRequest from 'UI/Functions/WebRequest';

..

webRequest("user/14")
    .then(response => {
        // response.json is the user object.
        // response also contains things like the status code and headers.
    })
    .catch(e => {
        // The request failed. This is often because the user is offline or there was no permission.
        // The given error object contains an error message and an error code.
        // Display to the user: e.message
        // For your functions, if you need to know what it was: e.code
    });

Simple POST request

POSTing to /v1/user to create a new user:

import webRequest from 'UI/Functions/WebRequest';

..

webRequest("user", {username: "helloWorld"})
    .then(response => {
        // response.json is the newly created user object.
        // response also contains things like the status code and headers.
    })
    .catch(e => {
        // The request failed. This is often because the user is offline or there was no permission.
        // The given error object contains an error message and an error code.
        // Display to the user: e.message
        // For your functions, if you need to know what it was: e.code
    });

Customise the http method for delete etc

Using a different http method (also called http verb) such as delete to delete a user here:

import webRequest from 'UI/Functions/WebRequest';

..

webRequest("user/14", null, {method: 'delete'})
    .then(response => {
        // response.json is the now deleted user object.
        // response also contains things like the status code and headers.
    })
    .catch(e => {
        // The request failed. This is often because the user is offline or there was no permission.
        // The given error object contains an error message and an error code.
        // Display to the user: e.message
        // For your functions, if you need to know what it was: e.code
    });

Specify a locale

This is a shortcut for specifying a header called Locale with a specific ID as its value. You would do this if you want to specifically obtain an object in a particular locale or update a particular locale:

import webRequest from 'UI/Functions/WebRequest';

..

webRequest("page/12", null, {locale: 2})
    .then(response => {
        // response.json is the contents of page #12, translated for locale #2.
        // response also contains things like the status code and headers.
    })
    .catch(e => {
        // The request failed. This is often because the user is offline or there was no permission.
        // The given error object contains an error message and an error code.
        // Display to the user: e.message
        // For your functions, if you need to know what it was: e.code
    });

Specify headers

The third arg also accepts a generic headers object. These are directly passed through to the fetch call.

import webRequest from 'UI/Functions/WebRequest';

..

webRequest("page/custom-endpoint", null, {headers: {HelloWorld: 'Yes'}})
    .then(response => {
        // response.json is the contents of whatever the custom endpoint responded with.
        // response also contains things like the status code and headers.
    })
    .catch(e => {
        // The request failed. This is often because the user is offline or there was no permission.
        // The given error object contains an error message and an error code.
        // Display to the user: e.message
        // For your functions, if you need to know what it was: e.code
    });