Class SxcWebApi

helper API to run ajax / REST calls to the server it will ensure that the headers etc. are set correctly and that urls are rewritten

sxc.webApi Helpers on the Sxc Controller

you are here (click to zoom) - discover the stack

The WebApi object on the App/Module-specific sxc-controller is for AJAX calls. It helps you in these advanced cases:

  1. to read/write content-items using REST
  2. to access your apps WebApi controllers

How to use

First you must ensure that you have the $2sxc manager on your page, which will get you a module-specific sxc controller. Read about the $2sxc global here.

Here's a simple example (assuming you have the $2sxc manager):

<a onclick="$2sxc(this).webApi.fetchJson('app/auto/data/Category').then(handleResult);">
    get all Categories 
</a>

The APIs to Get Data

  1. Modern fetchRaw and fetchJson API
  2. APIs to get URLs and headers

How to Get the Current Context's sxc Controller

Before you continue, make sure you know how to resolve/get your sxc-controller, as it is unique for each Dnn-Module. This is because each action needs to know which module it belongs to. Read about the 3 ways to get this in the $2sxc Manager docs. Here you'll also find out more about the sxc-controller.

History

  1. jQuery based webApi.get(...) etc. introduced in 2sxc 04.00 - see old docs
  2. fetchRaw(), fetchJson(), url(), headers() API introduced as beta in v12.10
  3. jQuery commands deprecated in v12.10 but will continue to work if the page has jQuery loaded
  4. url(...) enhanced with parameters object in v12.11
  5. fetchRaw(...) created to fix difficult naming in 12.10; fetch(...) is now deprecated and will stop working some day
  6. fetchRaw, fetchJson, sxc.data(...) and sxc.query(...) official for use 13.04
Package: Api.Js.SxcJs

Methods

delete(string | ZzzAjaxSettingsDeprecated, any, any, boolean)

Deprecated - docs in the separate interface

Declaration
function delete(settingsOrUrl: string | ZzzAjaxSettingsDeprecated, params?: any, data?: any, preventAutoFail?: boolean)
Parameters
Type Name Description
string | ZzzAjaxSettingsDeprecated settingsOrUrl
any params
any data
boolean preventAutoFail
Returns
Type Description
any

fetchJson(string, string | Record<string, any>, string)

Will retrieve data from the backend using a standard fetch and give you an object.

Declaration
function fetchJson<T>(url: string, data?: string | Record<string, any>, method?: string)
Parameters
Type Name Description
string url

a full url or short-hand like controller/method?params app/auto/api/controller/method?params. Note that params would also be specified on the url.
string | Record<string, any> data

optional POST data
string method

optional method, defaults to GET unless it has data, in which case it defaults to POST
Returns
Type Description
Promise<T>

a Promise containing any object.

fetchRaw(string, string | Record<string, any>, string)

Will retrieve data from the backend using a standard fetch.

Declaration
function fetchRaw(url: string, data?: string | Record<string, any>, method?: string)
Parameters
Type Name Description
string url

a full url or short-hand like controller/method?params app/auto/api/controller/method?params. Note that params would also be specified on the url.
string | Record<string, any> data

optional POST data
string method

optional method, defaults to GET unless it has data, in which case it defaults to POST
Returns
Type Description
Promise<Response>

a Promise containing a Response object, just like a normal fetch would. example: webApi.fetchRaw('Rss/Feed'); example: webApi.fetchRaw(webApi.url('Rss/Feed', { id: 47 })); // url params example: webApi.fetchRaw('Rss/Feed', { id: 47 }); // post params example: webApi.fetchRaw(webApi.url('Rss/Feed', { id: 47 }), { something: 'this is a test' }); // url & post params maybe: webApi.fetchRaw({url: 'Rss/Feed', params: { id: 47 }}) maybe: webApi.fetchRaw({url: ..., params: { ...}, body: { ...}, method: 'GET' })

get(string | ZzzAjaxSettingsDeprecated, any, any, boolean)

Deprecated - docs in the separate interface

Declaration
function get(settingsOrUrl: string | ZzzAjaxSettingsDeprecated, params?: any, data?: any, preventAutoFail?: boolean)
Parameters
Type Name Description
string | ZzzAjaxSettingsDeprecated settingsOrUrl
any params
any data
boolean preventAutoFail
Returns
Type Description
any

headers(string)

All the headers which are needed in an ajax call for this to work reliably. Use this if you need to get a list of headers in another system

Declaration
function headers(method?: string)
Parameters
Type Name Description
string method
Returns
Type Description
Record<string, string>

post(string | ZzzAjaxSettingsDeprecated, any, any, boolean)

Deprecated - docs in the separate interface

Declaration
function post(settingsOrUrl: string | ZzzAjaxSettingsDeprecated, params?: any, data?: any, preventAutoFail?: boolean)
Parameters
Type Name Description
string | ZzzAjaxSettingsDeprecated settingsOrUrl
any params
any data
boolean preventAutoFail
Returns
Type Description
any

put(string | ZzzAjaxSettingsDeprecated, any, any, boolean)

Deprecated - docs in the separate interface

Declaration
function put(settingsOrUrl: string | ZzzAjaxSettingsDeprecated, params?: any, data?: any, preventAutoFail?: boolean)
Parameters
Type Name Description
string | ZzzAjaxSettingsDeprecated settingsOrUrl
any params
any data
boolean preventAutoFail
Returns
Type Description
any

request(string | ZzzAjaxSettingsDeprecated, any, any, boolean, string)

Deprecated - docs in the separate interface

Declaration
function request(settings: string | ZzzAjaxSettingsDeprecated, params: any, data: any, preventAutoFail: boolean, method: string)
Parameters
Type Name Description
string | ZzzAjaxSettingsDeprecated settings
any params
any data
boolean preventAutoFail
string method
Returns
Type Description
any

url(string, string | Record<string, any>)

Declaration
function url(url: string, params?: string | Record<string, any>)
Parameters
Type Name Description
string url

A short, medium or long url. Short like controller/method, medium like app/auto/api/controller/method long like `https://xyz. In all cases it can also have ?params etc.
string | Record<string, any> params

Optional parameters as string or object, will be added to url-params.
Returns
Type Description
string

In the cases of a short/medium url, it will auto-expand to have the full url as needed for an API call.