API

API

Static API class to handle requests to the JAMES-API

Constructor

# new API()

Members

# (static) apikey :string

Holds the API-Key for the JAMES-API
Type:
  • string

Methods

# (static) BuildAPIURL(url) → {string}

Prepares the URL for an API request. Prepends the API-Prefix and adds auth data parameters to the URL
Parameters:
Name Type Description
url string the URL
Returns:
the resulting url to run the fetch with
Type
string
Example
let url = API.BuildAPIURL("/appointments/");
console.log(url);
// Outputs /restapi/{version}/appointments/?APIKEY={apikey} to the console

# (async, static) DELETE(url, data, overlay, isAPI, expectJSON, timeout) → {Promise}

DELETE Request function to make DELETE Requests
Parameters:
Name Type Default Description
url string the url to send the request to
data object | FormData | HTMLFormElement | string object: object containing key-value pairs; FormData: self-explaining; HTMLFormElement: the form element to serialize; string: a query selector string for a form element. See API.SerializeForm
overlay boolean true wether to show a "loading" overlay in the application or not
isAPI boolean true if true, authorization data is being added to the request and the url gets prependet "/restapi/{version}"
expectJSON boolean false if true, the fetch-promise gets awaited and is tried to parse to a data object
timeout number 30 the number of seconds after which the request is canceled and an error modal is being shown (Default: 30) If 0 or negative, the request won't time out
See:
Returns:
the Promise of the javascript fetch() OR if expectJSON is true, The Promise resolves directly to a data object or null if the request fails
Type
Promise

# (static) GET(url, overlay, isAPI, expectJSON, timeout) → {Promise}

GET Request function to make GET Requests
Parameters:
Name Type Default Description
url string the url to send the request to
overlay boolean true wether to show a "loading" overlay in the application or not
isAPI boolean true if true, authorization data is being added to the request and the url gets prependet "/restapi/{version}"
expectJSON boolean false if true, the fetch-promise gets awaited and is tried to parse to a data object
timeout number 30 the number of seconds after which the request is canceled and an error modal is being shown (Default: 30) If 0 or negative, the request won't time out
Returns:
the Promise of the javascript fetch() OR if expectJSON is true, The Promise resolves directly to a data object or null if the request fails
Type
Promise
Examples

Example 1 - expectJSON=true

let result = await API.GET("/appointments/",true,true,true);
if(result!==null)
{
    doSomethingWithTheResult();
}
else console.log("it failed");
// fetches a list of appointments from the JAMES-API, shows a loading overlay and saves the json decoded result object in "result"

Example 2 - expectJSON=false

let response = await API.GET("/appointments/",true,true,false); // returns the fetch()-Promise
if(response.ok) // Check for response code 2XX (success)
{
    let txt = await response.text();
    console.log(txt);
    doSomethingWithTheFullResponseText();
}
else console.log("it failed");
// fetches a list of appointments from the JAMES-API, shows a loading overlay and saves the whole fetch response to the response-variable

Example 3 - .then()-style

API.GET("/appointments/",true,true,false)
   .then(response => response.json())
   .then(data => doSeomeThingWithTheData)
   .catch(exc => console.log(exc));
// when expectJSON is false, you can do the same .then()-chain as you would do with fetch()

# (static) GetToken() → {string|null}

Gets the API key. if not already set, it checks the GET-Variables ?APIKEY and ?di_apikey until one is found
Returns:
the api key
Type
string | null

# (async, static) parseResponse(request) → {object|null}

Awaits the reuqest and parses json.
Parameters:
Name Type Description
request Promise the fetch()-Promise
Returns:
the parsed data object or null on fail
Type
object | null
Example
let request = fetch("/some/url/that/returns/json");
let data = await API.parseResponse(request);
// awaits the fetch promise and parses the json and stores it to the data variable

# (async, static) PATCH(url, data, overlay, isAPI, expectJSON, timeout) → {Promise}

PATCH Request function to make PATCH Requests
Parameters:
Name Type Default Description
url string the url to send the request to
data object | FormData | HTMLFormElement | string object: object containing key-value pairs; FormData: self-explaining; HTMLFormElement: the form element to serialize; string: a query selector string for a form element. See API.SerializeForm
overlay boolean true wether to show a "loading" overlay in the application or not
isAPI boolean true if true, authorization data is being added to the request and the url gets prependet "/restapi/{version}"
expectJSON boolean false if true, the fetch-promise gets awaited and is tried to parse to a data object
timeout number 30 the number of seconds after which the request is canceled and an error modal is being shown (Default: 30) If 0 or negative, the request won't time out
See:
Returns:
the Promise of the javascript fetch() OR if expectJSON is true, The Promise resolves directly to a data object or null if the request fails
Type
Promise

# (static) PING() → {Promise}

Checks a request to the echo-endpoint and measures the time until the response is being received.
Returns:
Type
Promise

# (async, static) POST(url, data, overlay, isAPI, expectJSON, timeout) → {Promise}

POST Request function to make POST Requests
Parameters:
Name Type Default Description
url string the url to send the request to
data object | FormData | HTMLFormElement | string object: object containing key-value pairs; FormData: self-explaining; HTMLFormElement: the form element to serialize; string: a query selector string for a form element. See API.SerializeForm
overlay boolean true wether to show a "loading" overlay in the application or not
isAPI boolean true if true, authorization data is being added to the request and the url gets prependet "/restapi/{version}"
expectJSON boolean false if true, the fetch-promise gets awaited and is tried to parse to a data object
timeout number 30 the number of seconds after which the request is canceled and an error modal is being shown (Default: 30) If 0 or negative, the request won't time out
Returns:
the Promise of the javascript fetch() OR if expectJSON is true, The Promise resolves directly to a data object or null if the request fails
Type
Promise
Examples

Example 1 - data is object

let result = await API.POST("/debug/",{someKey:someValue},true,true,true);
if(result!==null)
{
    doSomethingWithTheResult();
}
else console.log("it failed");
// posts {someKey:someValue} to the JAMES-API, shows a loading overlay and saves the json decoded result object in "result"

Example 2 - data is string

let result = await API.POST("/debug/","form#myForm",true,true,true);
if(result!==null)
{
    doSomethingWithTheResult();
}
else console.log("it failed");
// Takes the FormElement with the id #myForm and serializes it, then posts the serialized data to the JAMES-API, shows a loading overlay and saves the json decoded result object in "result"

# (async, static) PUT(url, data, overlay, isAPI, expectJSON, timeout) → {Promise}

PUT Request function to make PUT Requests
Parameters:
Name Type Default Description
url string the url to send the request to
data object | FormData | HTMLFormElement | string object: object containing key-value pairs; FormData: self-explaining; HTMLFormElement: the form element to serialize; string: a query selector string for a form element. See API.SerializeForm
overlay boolean true wether to show a "loading" overlay in the application or not
isAPI boolean true if true, authorization data is being added to the request and the url gets prependet "/restapi/{version}"
expectJSON boolean false if true, the fetch-promise gets awaited and is tried to parse to a data object
timeout number 30 the number of seconds after which the request is canceled and an error modal is being shown (Default: 30) If 0 or negative, the request won't time out
See:
Returns:
the Promise of the javascript fetch() OR if expectJSON is true, The Promise resolves directly to a data object or null if the request fails
Type
Promise

# (static) REQUEST(method, url, data, overlay, isAPI, expectJSON, timeout) → {Promise}

Generic Request function to make Request that are not GET Requests
Parameters:
Name Type Default Description
method "POST" | "PUT" | "PATCH" | "DELETE" | string the request method
url string the url to send the request to
data object | FormData | HTMLFormElement | string object: object containing key-value pairs; FormData: self-explaining; HTMLFormElement: the form element to serialize; string: a query selector string for a form element. See API.SerializeForm
overlay boolean true wether to show a "loading" overlay in the application or not
isAPI boolean true if true, authorization data is being added to the request and the url gets prependet "/restapi/{version}"
expectJSON boolean false if true, the fetch-promise gets awaited and is tried to parse to a data object
timeout number 30 the number of seconds after which the request is canceled and an error modal is being shown (Default: 30) If 0 or negative, the request won't time out
Returns:
the Promise of the javascript fetch() OR if expectJSON is true, The Promise resolves directly to a data object or null if the request fails
Type
Promise

# (static) SerializeForm(form) → {object}

Function to serialize a form to a data object
Parameters:
Name Type Description
form object | FormData | HTMLFormElement | string object: object containing key-value pairs; FormData: self-explaining; HTMLFormElement: the form element to serialize; string: a query selector string for a form element
Returns:
the resulting data object
Type
object
Examples

Example 1 - Type: object

let parsedData = API.ParseRequestData({hello:"test"});
// returns {hello:"test"}, so kinda useless here

Example 2 - Type: FormData

let f = new FormData();
f.append("hello","test");
let parsedData = API.ParseRequestData(f);
// returns {hello:"test"}

Example 3 - Type: HTMLFormElement

let form = j.query("form#myForm");
let parsedData = API.ParseRequestData(form);
// returns {hello:"test"}, if the input of name "hello" is set to value "test" in the form with id "myForm"

Example 4 - Type: string

let selectorString = "form#myForm";
let parsedData = API.ParseRequestData(selectorString);
// returns {hello:"test"}, if the input of name "hello" is set to value "test" in the form with id "myForm"