CrossBrowdy API documentation [printable]

Namespace: REST

CB_Net. REST

Static class to manage REST services and related. It will return itself if it is tried to be instantiated.

Source:
To Do:
  • Think about accepting an onAbort function as option (with also default and permanent).

Members

<static> SERVER_URL_DEFAULT :string

Defines the URL for the default REST server to use when the "serverURL" parameter is not available. Used by the CB_Net.XHR.callREST function as the default "serverURL" parameter.

Type:
  • string
Default Value:
  • http://localhost/CrossBrowdy/tests/net/fake_rest_server/index.php
Source:

<static> actions :Object

List of REST actions. Each property name is the name of the action and its value is a CB_Net.REST.actionProcess_ACTIONS object. Used by the CB_Net.REST.actionProcess function.

Type:
  • Object
Default Value:
  • {}
Source:

<static> allowedSuccessStatuses_DEFAULT :array

Default "allowedSuccessStatuses", containing the statuses to considerer a successful REST action (must be a numeric array of integers). Used by the CB_Net.REST.actionProcess function.

Type:
  • array
Default Value:
  • [200,201,206]
Source:

<static> allowedSuccessStatuses_PERMANENT :array

Permanent values for the "allowedSuccessStatuses" parameter, containing the statuses to considerer a successful REST action (must be a numeric array of integers). Used by the CB_Net.REST.actionProcess function. This is permanent for each REST action.

Type:
  • array
Default Value:
  • []
Source:

<static> avoidProxy_DEFAULT :boolean

Default value when the "avoidProxy" parameter is not available. Used by the CB_Net.REST.actionProcess function.


NOTE: Edit the "CB_proxy.config.php" file to configure the default proxy (set by default in the value of the CB_Configuration.CrossBase.CB_Net_XHR_PROXY_URL property). Apart from configuring it, adding some security measures is highly recommended.
Have in mind that, for safety reasons, the default proxy only allows to request the URLs defined in the "$allowedURLs" array in the "CB_proxy.config.php" file. Just edit it to allow other URLs.

Type:
  • boolean
Source:

<static> callbackBefore_DEFAULT :CB_Net.REST.actionProcess_CALLBACK_BEFORE

Default "callbackBefore", containing a callback function before performing each REST action returning a boolean (to decide whether to do it or not). The function assigned by default returns true. Used by the CB_Net.REST.actionProcess function.

Type:
Source:

<static> callbackBefore_PERMANENT :CB_Net.REST.actionProcess_CALLBACK_BEFORE

Permanent callback function before performing each REST action returning a boolean (to decide whether to do it or not). Executed before the default or the set "callbackBefore" function (if any). The function assigned by default returns true. Used by the CB_Net.REST.actionProcess function. This is permanent for each REST action.

Type:
Source:

<static> callbackError_DEFAULT :CB_Net.REST.actionProcess_CALLBACK_ERROR

Default "callbackError", containing a callback function when an error happens processing the REST action. Used by the CB_Net.REST.actionProcess function.

Type:
Source:

<static> callbackError_PERMANENT :CB_Net.REST.actionProcess_CALLBACK_ERROR

Permanent callback function when an error happens processing any REST action. Used by the CB_Net.REST.actionProcess function. Executed before the default or the set "callbackError" function (if any). This is permanent for each REST action.

Type:
Source:

<static> callbackOk_DEFAULT :CB_Net.REST.actionProcess_CALLBACK_OK

Default "callbackOk", containing a callback function when the REST action has been successful. Used by the CB_Net.REST.actionProcess function.

Type:
Source:

<static> callbackOk_PERMANENT :CB_Net.REST.actionProcess_CALLBACK_OK

Permanent callback function when each REST action has been successful. Used by the CB_Net.REST.actionProcess function. Executed before the default or the set "callbackOk" function (if any). This is permanent for each REST action.

Type:
Source:

<static> dataURL_DEFAULT :CB_Net.REST.actionProcess_DATA_URL

Default "dataURL" for REST actions (must return a string in URL/GET parameters format). The function assigned by default returns an empty string (""). Used by the CB_Net.REST.actionProcess function. NOTE: remember to use CB_Net.URLValueEncode if needed.

Type:
Source:

<static> dataURL_PERMANENT :CB_Net.REST.actionProcess_DATA_URL

Permanent function (must return a string in URL/GET parameters format) to execute the same way as the "dataURL" parameter. The function assigned by default returns an empty string (""). Used by the CB_Net.REST.actionProcess function. The returning data will be placed in the beginning of the URL, followed by the rest of the "dataURL" desired (if any). NOTE: remember to use CB_Net.URLValueEncode if needed. This is permanent for each REST action.

Type:
Source:

<static> data_DEFAULT :CB_Net.REST.actionProcess_DATA

Default "data" for REST actions (must return a string in URL/GET parameters format or a JSON format string). The function assigned by default returns an empty string (""). Used by the CB_Net.REST.actionProcess function. The values returned by all functions that are mean to return the data should always return the same type of data (all strinngs or all objects) since CB_Net.REST.actionProcess will use the CB_combineAutomatically function to combine them. NOTE: remember to use CB_Net.URLValueEncode if needed.

Type:
Source:

<static> data_PERMANENT :CB_Net.REST.actionProcess_DATA

Permanent function (must return a string in URL/GET parameters format or a JSON format string) to execute the same way as the "data" parameter. The function assigned by default returns an empty string (""). Used by the CB_Net.REST.actionProcess function. The values returned by all functions that are mean to return the data should always return the same type of data (all strinngs or all objects) since CB_Net.REST.actionProcess will use the CB_combineAutomatically function to combine them. This is permanent for each REST action. NOTE: remember to use CB_Net.URLValueEncode if needed.

Type:
Source:

<static> forceJSON_DEFAULT :boolean

Tells whether to force JSON response by default or not. Used by the CB_Net.REST.actionProcess function when the REST action does not provided it and it is not null, as the "forceJSON" option.

Type:
  • boolean
Default Value:
  • true
Source:

<static> getHeadersOneDimensionValues_DEFAULT :boolean

Tells whether to get response HTTP headers values in one-dimension (just one value per key) by default or not (needs "getHeaders" set to true). Used by the CB_Net.REST.actionProcess function when the REST action does not provided it and it is not null, as the "getHeadersOneDimensionValues" option.

Type:
  • boolean
Source:

<static> getHeadersOneDimension_DEFAULT :boolean

Tells whether to get response HTTP headers in one-dimension array by default or not (needs "getHeaders" set to true). Used by the CB_Net.REST.actionProcess function when the REST action does not provided it and it is not null, as the "getHeadersOneDimension" option.

Type:
  • boolean
Source:

<static> getHeaders_DEFAULT :boolean

Tells whether get response HTTP headers by default or not. Used by the CB_Net.REST.actionProcess function when the REST action does not provided it and it is not null, as the "getHeaders" option.

Type:
  • boolean
Source:

<static> headers_DEFAULT :CB_Net.REST.actionProcess_HEADERS

Default "headers" for REST actions (must be a function returning a CB_Net.XHR.HEADERS object with the HTTP headers). The function assigned by default returns { "Content-Type" : "application/x-www-form-urlencoded; charset=UTF-8" }. Used by the CB_Net.REST.actionProcess function.

Type:
Source:

<static> headers_PERMANENT :CB_Net.REST.actionProcess_HEADERS

Permanent function (must be a function returning a CB_Net.XHR.HEADERS object with the HTTP headers) to execute the same way as the "headers" parameter. The function assigned by default returns { "Cache-Control" : "no-cache", "Pragma" : "no-cache" }. Used by the CB_Net.REST.actionProcess function. This is permanent for each REST action.

Type:
Source:

<static> method_DEFAULT :string

Default "method" for REST actions. Used by the CB_Net.REST.actionProcess function.

Type:
  • string
Default Value:
  • GET
Source:

<static> responseType_DEFAULT :string

Default "responseType" for REST actions when it is not provided and it is not null. Used by the CB_Net.REST.actionProcess function.

Type:
  • string
Default Value:
  • text
Source:

<static> routeWildcardData_DEFAULT :CB_Net.REST.actionProcess_ROUTE_WILDCARD_DATA

Default "routeWildcardData" for REST actions (must be a function returning a JSON object or null if we do not want to modify the route). The function assigned by default returns null. Used by the CB_Net.REST.actionProcess function.

Type:
Source:

<static> routeWildcardData_PERMANENT :CB_Net.REST.actionProcess_ROUTE_WILDCARD_DATA

Permanent function (must return a JSON object or null if we do not want to modify it) to execute the same way as the "routeWildcardData" parameter (if other "routeWildcardData" are provided or set, they will be executed before this one). The function assigned by default returns null. Used by the CB_Net.REST.actionProcess function. This is permanent for each REST action.

Type:
Source:

<static> transparentHeaders_DEFAULT :boolean

Tells whether get HTTP headers transparently from the server by default or not. Used by the CB_Net.REST.actionProcess function when the REST action does not provided it and it is not null, as the "transparentHeaders" option.

Type:
  • boolean
Default Value:
  • true
Source:

<static> transparentStatus_DEFAULT :boolean

Tells whether get status transparently from the server by default or not. Used by the CB_Net.REST.actionProcess function when the REST action does not provided it and it is not null, as the "transparentStatus" option.

Type:
  • boolean
Default Value:
  • true
Source:

Methods

<static> actionAbort(XHR) → {boolean}

Cancels a REST action (by its AJAX/XHR request associated) by executing the "abort" method of the given XHR object (if available) and sets its "aborted" property to true if succeeds. When a REST action is aborted, the callbackOk functions associated (if any) will not be called (unless they have been called already).

Parameters:
Name Type Description
XHR Object

The XHR object that we want to abort.
Source:
Returns:

Returns true if the "abort" method of the given XHR object could be called and the "aborted" property was set to true. Otherwise, returns false.

Type
boolean

<static> actionAbortCancel(XHR) → {boolean}

Tries to revert the abortion of a REST action (by its AJAX/XHR request associated) by setting the "aborted" property of the given XHR object to false. If this function is called before the "callbackOk" functions associated to the REST action (if any) are called, they could finally be called perhaps (depending on each case, could be different). Have in mind that, after calling CB_Net.REST.actionAbort, the "abort" method of the XHR object was probably called already (if available).

Parameters:
Name Type Description
XHR Object

The XHR object whose abortion we want to cancel.
Source:
Returns:

Returns true if the "aborted" property was set to false. Otherwise, returns false.

Type
boolean

<static> actionIsAborted(XHR) → {boolean}

Returns whether a REST action is aborted or not (by its AJAX/XHR request associated).

Parameters:
Name Type Description
XHR Object

The XHR object that we want to check.
Source:
Returns:

Returns true if the "aborted" property is set to true. Otherwise, returns false.

Type
boolean

<static> actionProcess(actionName [, additionalData] [, XHR] [, serverURL] [, avoidProxy]) → {Object|null}

Processes a desired REST action (which must be previously defined in the CB_Net.REST.actions object) by its name.


NOTE: Edit the "CB_proxy.config.php" file to configure the default proxy (set by default in the value of the CB_Configuration.CrossBase.CB_Net_XHR_PROXY_URL property). Apart from configuring it, adding some security measures is highly recommended.
Have in mind that, for safety reasons, the default proxy only allows to request the URLs defined in the "$allowedURLs" array in the "CB_proxy.config.php" file. Just edit it to allow other URLs.

Parameters:
Name Type Argument Description
actionName string

The name of the REST action that we want to perform. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
additionalData * <optional>

Any additional data desired. It will be passed as a parameter when different callbacks are called internally, as their "additionalData" parameter.
XHR Object <optional>

Used for the "XHR" parameter of the CB_Net.XHR.callREST function when it is called internally.
serverURL string <optional>

Used for the "serverURL" parameter of the CB_Net.XHR.callREST function when it is called internally. If provided, the value defined in the "serverURL" parameter of the REST action being performed (if any) will be ignored.
avoidProxy boolean <optional>

Used for the "avoidProxy" parameter of the CB_Net.XHR.callREST function when it is called internally. If provided, the value defined in the "avoidProxy" parameter of the REST action being performed (if any) and the default one defined in CB_Net.REST.avoidProxy_DEFAULT (if any) will be both ignored.
Source:
Returns:

Returns null if the CB_Net.XHR.callREST function is not called at all (because XHR is not supported or the REST action object cannot be found or the route is not well defined or the "callbackBefore" returns false, etc.). Otherwise, returns the same that the CB_Net.XHR.callREST function returns (called internally).

Type
Object | null

Type Definitions

actionProcess_ACTIONS

Object that represents a REST action.

Type:
  • Object
Properties:
Name Type Argument Default Description
route string

The REST route (path). Belongs to the "route" parameter of the CB_Net.XHR.callREST function when it is called internally. It is mandatory.
callbackBefore CB_Net.REST.actionProcess_CALLBACK_BEFORE <optional>
 CB_Net.REST.callbackBefore_DEFAULT

Callback run before performing the REST action which will decide whether to continue with it or not.
avoidProxy boolean <optional>
 CB_Net.REST.avoidProxy_DEFAULT

Belongs to the "avoidProxy" parameter of the CB_Net.XHR.callREST function when it is called internally.
routeWildcardData CB_Net.REST.actionProcess_ROUTE_WILDCARD_DATA <optional>
 CB_Net.REST.routeWildcardData_DEFAULT

Callback returning an object that will be used for parsing the REST route. The object returned should follow the same rules as the "JSONObject" parameter of the CB_renderString function.
dataURL CB_Net.REST.actionProcess_DATA_URL <optional>
 CB_Net.REST.dataURL_DEFAULT

Belongs to the "dataURL" parameter of the CB_Net.XHR.callREST function when it is called internally.
data CB_Net.REST.actionProcess_DATA <optional>
 CB_Net.REST.data_DEFAULT

Belongs to the "data" parameter of the CB_Net.XHR.callREST function when it is called internally.
headers CB_Net.REST.actionProcess_HEADERS <optional>
 CB_Net.REST.headers_DEFAULT

Belongs to the "headers" parameter of the CB_Net.XHR.callREST function when it is called internally.
allowedSuccessStatuses array <optional>
 CB_Net.REST.allowedSuccessStatuses_DEFAULT

Belongs to the "allowedSuccessStatuses" parameter of the CB_Net.XHR.callREST function when it is called internally.
callbackError CB_Net.REST.actionProcess_CALLBACK_ERROR <optional>
 CB_Net.REST.callbackError_DEFAULT

Callback run when the REST action has not been performed successfully.
callbackOk CB_Net.REST.actionProcess_CALLBACK_OK <optional>
 CB_Net.REST.callbackOk_DEFAULT

Callback run when the REST action has been performed successfully.
serverURL string <optional>
 CB_Net.REST.SERVER_URL_DEFAULT

Belongs to the "serverURL" parameter of the CB_Net.XHR.callREST function when it is called internally.
method string <optional>
 CB_Net.REST.method_DEFAULT

Belongs to the "method" parameter of the CB_Net.XHR.callREST function when it is called internally.
responseType string <optional>
 CB_Net.REST.responseType_DEFAULT

Belongs to the "responseType" parameter of the CB_Net.XHR.callREST function when it is called internally and will be sent even it is null. If it is undefined, it will use the value of CB_Net.REST.responseType_DEFAULT instead.
forceJSON boolean <optional>
 CB_Net.REST.forceJSON_DEFAULT

Belongs to the "forceJSON" parameter of the CB_Net.XHR.callREST function when it is called internally and will be sent even it is null. If it is undefined, it will use the value of CB_Net.REST.forceJSON_DEFAULT instead.
getHeaders boolean <optional>
 CB_Net.REST.getHeaders_DEFAULT

Belongs to the "getHeaders" parameter of the CB_Net.XHR.callREST function when it is called internally and will be sent even it is null. If it is undefined, it will use the value of CB_Net.REST.getHeaders_DEFAULT instead.
getHeadersOneDimension boolean <optional>
 CB_Net.REST.getHeadersOneDimension_DEFAULT

Belongs to the "getHeadersOneDimension" parameter of the CB_Net.XHR.callREST function when it is called internally and will be sent even it is null. If it is undefined, it will use the value of CB_Net.REST.getHeadersOneDimension_DEFAULT instead.
getHeadersOneDimensionValues boolean <optional>
 CB_Net.REST.getHeadersOneDimensionValues_DEFAULT

Belongs to the "getHeadersOneDimensionValues" parameter of the CB_Net.XHR.callREST function when it is called internally and will be sent even it is null. If it is undefined, it will use the value of CB_Net.REST.getHeadersOneDimensionValues_DEFAULT instead.
transparentStatus boolean <optional>
 CB_Net.REST.transparentStatus_DEFAULT

Belongs to the "transparentStatus" parameter of the CB_Net.XHR.callREST function when it is called internally and will be sent even it is null. If it is undefined, it will use the value of CB_Net.REST.transparentStatus_DEFAULT instead.
transparentHeaders boolean <optional>
 CB_Net.REST.transparentHeaders_DEFAULT

Belongs to the "transparentHeaders" parameter of the CB_Net.XHR.callREST function when it is called internally and will be sent even it is null. If it is undefined, it will use the value of CB_Net.REST.transparentHeaders_DEFAULT instead.
Source:

actionProcess_CALLBACK_BEFORE(actionName, additionalData) → {boolean}

Callback that will be run before performing a REST action and must return a boolean defining whether we want to continue performing the action (returning true) or not (returning false).

Parameters:
Name Type Description
actionName string

The name of the REST action being performed. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
additionalData *

Any additional data associated to the REST action being performed (belongs to the "additionalData" parameter used when the CB_Net.REST.actionProcess function was called).
Source:
Returns:

It should return true in the case that we want to continue performing the current REST action or false otherwise.

Type
boolean

actionProcess_CALLBACK_ERROR(actionName [, XHR], additionalData)

Callback that will be run when the REST action has been performed successfully.

Parameters:
Name Type Argument Description
actionName string

The name of the REST action being performed. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
XHR Object <optional>

The XHR object that has been used to perform the REST action.
additionalData *

Any additional data associated to the REST action being performed (belongs to the "additionalData" parameter used when the CB_Net.REST.actionProcess function was called).
Source:

actionProcess_CALLBACK_OK(actionName [, XHR], callbackError, additionalData)

Callback that will be run when the REST action has been performed successfully.

Parameters:
Name Type Argument Description
actionName string

The name of the REST action being performed. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
XHR Object <optional>

The XHR object that has been used to perform the REST action.
callbackError CB_Net.REST.actionProcess_CALLBACK_ERROR

The error callback function associated to the REST action being performed, just in case we want to call it.
additionalData *

Any additional data associated to the REST action being performed (belongs to the "additionalData" parameter used when the CB_Net.REST.actionProcess function was called).
Source:

actionProcess_DATA(actionName, additionalData) → {string|Object}

Callback returning the data (string or object) which will be used as the "data" parameter when the CB_Net.XHR.callREST function is called internally by CB_Net.REST.actionProcess. The values returned by all functions that are mean to return the data should always return the same type of data (all strinngs or all objects) since CB_Net.REST.actionProcess will use the CB_combineAutomatically function to combine them.

Parameters:
Name Type Description
actionName string

The name of the REST action being performed. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
additionalData *

Any additional data associated to the REST action being performed (belongs to the "additionalData" parameter used when the CB_Net.REST.actionProcess function was called).
Source:
Returns:

It should return a string or object containing the data. Return null or an empty string (recommended) in the case that we do not want to add anything. The value returned (if any) will be used as the "data" parameter of the CB_Net.XHR.callREST function when it is called by CB_Net.REST.actionProcess internally.

Type
string | Object

actionProcess_DATA_URL(actionName, additionalData) → {string}

Callback returning a string containing the URL (GET) data which will be used as the "dataURL" parameter when the CB_Net.XHR.callREST function is called internally by CB_Net.REST.actionProcess.

Parameters:
Name Type Description
actionName string

The name of the REST action being performed. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
additionalData *

Any additional data associated to the REST action being performed (belongs to the "additionalData" parameter used when the CB_Net.REST.actionProcess function was called).
Source:
Returns:

It should return a string containing the URL (GET) data. Return an empty string in the case that we do not want to add anything. The string returned (if any) will be used as the "dataURL" parameter of the CB_Net.XHR.callREST function when it is called by CB_Net.REST.actionProcess internally.

Type
string

actionProcess_HEADERS(actionName, additionalData) → {CB_Net.XHR.HEADERS|null}

Callback returning an object containing the HTTP headers which will be used as the "headers" parameter when the CB_Net.XHR.callREST function is called internally by CB_Net.REST.actionProcess.

Parameters:
Name Type Description
actionName string

The name of the REST action being performed. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
additionalData *

Any additional data associated to the REST action being performed (belongs to the "additionalData" parameter used when the CB_Net.REST.actionProcess function was called).
Source:
Returns:

It should return an object containing the HTTP headers. Return null in the case that we do not want to add anything. The object returned (if any) will be used as the "headers" parameter of the CB_Net.XHR.callREST function when it is called by CB_Net.REST.actionProcess internally.

Type
CB_Net.XHR.HEADERS | null

actionProcess_ROUTE_WILDCARD_DATA(actionName, additionalData) → {Object|null}

Callback returning an object that will be used for parsing the REST route. The object returned should follow the same rules as the "JSONObject" parameter of the CB_renderString function.

Parameters:
Name Type Description
actionName string

The name of the REST action being performed. It should be the name of an index defined in the CB_Net.REST.actions object whose value should be a CB_Net.REST.actionProcess_ACTIONS object.
additionalData *

Any additional data associated to the REST action being performed (belongs to the "additionalData" parameter used when the CB_Net.REST.actionProcess function was called).
Source:
Returns:

It should return an object containing the wildcards that will be used to parse the REST route of the action being performed. Return null in the case that we do not want to modify anything. The object returned (if any) will be used as the "JSONObject" parameter of the CB_renderString function (the first parameter will be the route which should be a string) when it is called by CB_Net.REST.actionProcess internally.

Type
Object | null