Server Communication - Documentation

Server Communication - Guide

Brain Annex supports and uses 2 separate web API protocols:

SIMPLE TEXT PROTOCOL	Return a string with the payload or error, prefixed by the single character "+" or "-" respectively in case of success or failure	Example of successful return value: `+san francisco` Example of failure return value: `-unauthorized access`
JSON PROTOCOL	Return a JSON string with a structured response. if successful, 2 keys are expected: "status" (containing the value "ok") and "payload" (with the actual data) in case of failure, 2 keys are expected: "status" (containing the value "error") and "error_message" (with details)	Example of successful return value: `{"status": "ok", "payload": {"city": "san francisco", "state": "CA"}}` Example of failure return value: `{"status": "error", "error_message": "unauthorized access"}`

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 either of the above 2 protocols.

Note: by convention, Brain Annex uses /simple/ in the url's of the api endpoints that make use of the "simple text protocol" described above.

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!
    // CHANGE "JSON" to "TEXT" if you're using the simple text protocol
    ServerCommunication.contact_server(url_server_api,
                {payload_type: "JSON",
                 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!
    // CHANGE "JSON" to "TEXT" if you're using the simple text protocol
    ServerCommunication.contact_server(url_server_api,
                {payload_type: "JSON",
                 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
    // ...
}