Server Communication - Guide

This guide is for versions Beta 35.1+

Brain Annex supports and uses the following web API protocol:

The small JavaScript library ServerCommunication provides a thin wrapper around the standard fetch() API, to simplify the process by which the front-end can communicates with the server, and to streamline the use of the above protocol.

Below are some examples of communication with the server from the front-end. Watch out for the parts to change as needed!

IMPORTANT: the syntax in the examples is for use with Vue.js ; if you're not using Vue, remember to prefix the "function" keywords, to drop the commas at the end of the functions, and to drop the "this." from the names!
(in the examples, we're assuming we're using the Vue state variables this.waiting, this.error, this.status_message to let Vue update the UI display; change as neeeded.)

Example of Asynchronous server call using POST data

get_data_from_server_POST(example_arg)          /* "POST"  version */
/* Initiate request to server
 */
{
    console.log(`Invoking get_data_from_server_POST() with argument '${example_arg}'`);
    
    // CHANGE AS NEEDED!
    const url_server_api = "/BA/api/SOME_API_ENDPOINT"; // URL to communicate with the server's API endpoint
    let post_obj = {some_key: some_value, more_keys: more_values};
    let my_optional_var = some optional value;          // Optional parameter, if needed (of any type)

    this.waiting = true;        // Entering a waiting-for-server mode
    this.error = false;         // Clear any error from the previous operation
    this.status_message = "";   // Clear any message from the previous operation

    console.log(`About to contact the server at ${url_server_api}.  POST object:`);
    console.log(post_obj);
    
    // Initiate asynchronous contact with the server, using POST data; notice the callback function!
    ServerCommunication.contact_server(url_server_api,
                {post_obj: post_obj,
                 callback_fn: this.finish_get_data_from_server,
                 custom_data: my_optional_var
                 });
},

Example of Asynchronous server call using GET data

get_data_from_server_GET(example_arg)          /* "GET"  version */
/* Initiate request to server
 */
{
    console.log(`Invoking get_data_from_server_GET() with argument '${example_arg}'`);

    // CHANGE AS NEEDED!
    const url_server_api = "/BA/api/SOME_API_ENDPOINT"; // URL to communicate with the server's API endpoint
    let my_optional_var = some optional value;          // Optional parameter, if needed (of any type)
    
    this.waiting = true;        // Entering a waiting-for-server mode
    this.error = false;         // Clear any error from the previous operation
    this.status_message = "";   // Clear any message from the previous operation

    console.log(`About to contact the server at ${url_server_api}`);
    
    // Initiate asynchronous contact with the server, using GET data; notice the callback function!
    ServerCommunication.contact_server(url_server_api,
                {callback_fn: this.finish_get_data_from_server,
                 custom_data: my_optional_var
                 });
},

Example of Callback function

finish_get_data_from_server(success, server_payload, error_message, custom_data)
/* Callback function to wrap up the action of get_data_from_server() upon getting a response from the server

        success:        boolean indicating whether the server call succeeded
        server_payload: whatever the server returned (STRIPPED of protocol-related information about the status of the operation)
        error_message:  a string only applicable in case of failure
        custom_data:    whatever JavaScript structure, if any, was passed as argument to the contact_server() call
 */
{
    console.log("Finalizing the get_data_from_server operation...");
    
    if (success)  {     // Server reported SUCCESS
        console.log("    server call was successful; it returned: ", server_payload);
        this.status_message = `Operation completed`;
        // do something with the server_payload value
        // ...
    }
    else  {             // Server reported FAILURE
        this.error = true;
        this.status_message = `FAILED operation: ${error_message}`;
        // do something with the error_message value 
        // ...
    }

    // Final wrap-up, regardless of error or success
    this.waiting = false;      // Make a note that the asynchronous operation has come to an end
    // Ops to do at the end in either case
    // ...
}