Server Side Events (SSE)

19min
Overview
Server-Sent Events (SSE)is a server push technology that enables a client to receive automatic updates from a server over an HTTP connection. Once the initial client connection is established, the server can continuously push real-time data to the client without requiring repeated requests. 
OS1 makes SSE easy to implement, enabling developers to set up real-time data streaming with minimal effort. It reduces management overhead while ensuring reliable and scalable event-driven communication. 
The Server Side Events (SSE) feature enables app developers to build more responsive web applications with the ability to receive real-time response data directly from the Console UI. This is achieved through a Server-Sent Event communication, enabling a seamless and immediate data flow from the Console to the web app upon initiating an API request. The native push-based data delivery not only enables faster, real-time frontend experiences but also streamlines infrastructure efficiency.
📘 Note﻿
This feature is only available for web apps that integrate with Console. 
Prerequisites
To Implement SSE, you need to instantiate the OS1HttpClient from the Console UI. The OS1HttpClient is a wrapper HTTP client provided by the Console UI to make it easier to support POST, PUT, PATCH, DELETE HTTP methods necessary for RESTful API calls. It is a pre-configured instance of Axios that handles authentication, base URLs, and other HTTP client best practices.
JS
// Import from Console UI context
import { OS1HttpClient } from 'console/http';

// Instantiate 
const httpClient = new OS1HttpClient(
  consoleContext.authInitializer,
  process.env.BASE_URL  
);
// Import from Console UI context
import { OS1HttpClient } from 'console/http';

// Instantiate 
const httpClient = new OS1HttpClient(
  consoleContext.authInitializer,
  process.env.BASE_URL  
);
﻿
The OS1HttpClient takes two arguments:
The first is props.console.authInitializer, which contains the authentication context or initialization parameters necessary for the client to make authenticated requests.
The second argument is the process.env.BASE_URL is for the API endpoints that the application will communicate with.
The SSE client ID has a lifespan of 1 hour. If this limit is exceeded, the API will throw an error. To establish a connection again, you need to refresh the page.
Implementation
This guide details the integration of Server-Side Events (SSE) using the OS1HttpClient class provided by the Console, allowing for real-time communication from server to client in your application. There are two ways to implement Server Side Events (SSE) in your application:
Option 1: Using the {{SSE_CALLBACK}} Placeholder
This is the simplest option if using the Console’s Axios client.
Step 1: Setting the Callback URL Parameter
When making an API call, specify the attribute where the callback url is expected on the backend and its value needs to be set by using the placeholder {{SSE_CALLBACK}}. The Console will automatically detect and replace this placeholder with the actual callback URL. Developers can pass the callback attribute in the request URL, headers, or the request body.
The example below adds {{SSE_CALLBACK}} to the header for the createVehicles request.
JS
try {
  await axiosClient.post(
    '/vehicles',
    dto, // The payload for the API call
    'createVehicles', // The operation or function being called
    { withAuth: false }, // Options, set to false if authentication is not required
    {
      headers: {
        'Callback': "{{SSE_CALLBACK}}", // Updated automatically by the Axios Client
        'Content-Type': 'application/json', // Set the content type of the request
      }
    }
  );
} catch (error) {
  console.error('error', error);
}
try {
  await axiosClient.post(
    '/vehicles',
    dto, // The payload for the API call
    'createVehicles', // The operation or function being called
    { withAuth: false }, // Options, set to false if authentication is not required
    {
      headers: {
        'Callback': "{{SSE_CALLBACK}}", // Updated automatically by the Axios Client
        'Content-Type': 'application/json', // Set the content type of the request
      }
    }
  );
} catch (error) {
  console.error('error', error);
}
﻿
Internally, the OS1HttpClient will manage the SSE connection and retrieve the callback URL from the server if the {{SSE_CALLBACK}} placeholder is present and will replace the variable where the callback URL is needed in the API request.
Step 2: Listen to SSE Events
Once a callback is received from the server, the Console will emit a custom event, SSECallBackEvent. Your application needs to listen to this event in your UI code and handle the data when the API response is pushed from the server.
JS
document.addEventListener(`${consoleInstance.events().SSECallBackEvent}`, (eventData) => {
  // Handle the event data
});
document.addEventListener(`${consoleInstance.events().SSECallBackEvent}`, (eventData) => {
  // Handle the event data
});
﻿
JS
const dto = {
  callback: {
    url: "{{SSE_CALLBACK}}",
    meta: {},
  },
};
try {
  await axiosClient.delete(
    `/vehicles/${vehicleId}`,
    dto, // The payload for the API call
    "deleteVehicles", // The operation or function being called
    {withAuth: false}, // Options, set to false if authentication is not required
    {
      headers: {
        Callback: "{{SSE_CALLBACK}}", // Updated automatically by the Axios Client
        "Content-Type": "application/json", // Set the content type of the request
      },
    }
  );
} catch (error) {
  console.error("error", error);
}
const dto = {
  callback: {
    url: "{{SSE_CALLBACK}}",
    meta: {},
  },
};
try {
  await axiosClient.delete(
    `/vehicles/${vehicleId}`,
    dto, // The payload for the API call
    "deleteVehicles", // The operation or function being called
    {withAuth: false}, // Options, set to false if authentication is not required
    {
      headers: {
        Callback: "{{SSE_CALLBACK}}", // Updated automatically by the Axios Client
        "Content-Type": "application/json", // Set the content type of the request
      },
    }
  );
} catch (error) {
  console.error("error", error);
}
﻿
DELETE request with {{SSE_CALLBACK}}
The OS1HttpClient can handle DELETE requests with SSE. Users can pass {{SSE_CALLBACK}} in the headers, data payload, or query parameters, allowing the console to intercept the request and replace {{SSE_CALLBACK}} with the actual SSE callback URL.
The example below shows a DELETE request by passing {{SSE_CALLBACK}} in both the header and payload.
javascrip
```javascript
const dto = {
  callback: {
    url: "{{SSE_CALLBACK}}",
    meta: {},
  },
};
try {
  await axiosClient.delete(
    `/vehicles/${vehicleId}`,
    dto, // The payload for the API call
    "deleteVehicles", // The operation or function being called
    {withAuth: false}, // Options, set to false if authentication is not required
    {
      headers: {
        Callback: "{{SSE_CALLBACK}}", // Updated automatically by the Axios Client
        "Content-Type": "application/json", // Set the content type of the request
      },
    }
  );
} catch (error) {
  console.error("error", error);
}
```
```javascript
const dto = {
  callback: {
    url: "{{SSE_CALLBACK}}",
    meta: {},
  },
};
try {
  await axiosClient.delete(
    `/vehicles/${vehicleId}`,
    dto, // The payload for the API call
    "deleteVehicles", // The operation or function being called
    {withAuth: false}, // Options, set to false if authentication is not required
    {
      headers: {
        Callback: "{{SSE_CALLBACK}}", // Updated automatically by the Axios Client
        "Content-Type": "application/json", // Set the content type of the request
      },
    }
  );
} catch (error) {
  console.error("error", error);
}
```
﻿
Error Handling
If there are any internal errors during connection setup, the Console will throw an error, and an API call will be made with null as the callback URL. Only non-retriable errors will be thrown to the user.
Example Implementation
The following sample code demonstrates the full implementation for using the {{SSE_CALLBACK}} placeholder:
JS
// Import and instantiate HTTP client
import { OS1HttpClient } from 'console/http';

const httpClient = new OS1HttpClient(consoleContext.authInitializer, BASE_URL);

// Make API request with placeholder   
const makeRequest = async () => {

  try {
    const response = await httpClient.post('/api', data, {
      headers: {
        'Callback': '{{SSE_CALLBACK}}' 
      }
    });

    console.log(response);

  } catch (error) {
    console.error(error);
  }

};

// Listen for callback event
document.addEventListener(consoleContext.events.SSECallbackEvent, (event) => {
  const data = event.data; // callback payload

  // Handle data 
});

// Initiate request
makeRequest();
// Import and instantiate HTTP client
import { OS1HttpClient } from 'console/http';

const httpClient = new OS1HttpClient(consoleContext.authInitializer, BASE_URL);

// Make API request with placeholder   
const makeRequest = async () => {

  try {
    const response = await httpClient.post('/api', data, {
      headers: {
        'Callback': '{{SSE_CALLBACK}}' 
      }
    });

    console.log(response);

  } catch (error) {
    console.error(error);
  }

};

// Listen for callback event
document.addEventListener(consoleContext.events.SSECallbackEvent, (event) => {
  const data = event.data; // callback payload

  // Handle data 
});

// Initiate request
makeRequest();
﻿
The implementation does the following:
Imports and instantiates the OS1HttpClient
Makes an API call with the {{SSE_CALLBACK}} placeholder
Console will swap the placeholder with the actual URL
Listens for the SSECallbackEvent callback
The event data contains the response payload.
Option 2: Calling the getEventBrokerUrl
This option works with any HTTP client and is not limited to Console’s Axios client.
Step 1: Call the getEventBrokerUrl
When you are ready to make an API call, ensure that the getEventBrokerUrl function is invoked to verify or refresh the callback URL. This function will maintain the connection and provide the callback URL for the API request. See the example code below:
JS
const callbackResponse = await cl.getEventBrokerUrl();
setCallBackUrl(callbackResponse.callback); // Set the new callback URL in state
const callbackResponse = await cl.getEventBrokerUrl();
setCallBackUrl(callbackResponse.callback); // Set the new callback URL in state
﻿
Step 2: Store the returned callback URL
Store the returned callback URL in a component state variable or global context object. This allows referencing it when making API calls.
JS
// Store in component state
const [callbackUrl, setCallbackUrl] = useState(null);

const getUrl = async () => {
  const url = await httpClient.getEventBrokerUrl();
  setCallbackUrl(url); 
}

// Store in global context
context.callbackUrl = await httpClient.getEventBrokerUrl();
// Store in component state
const [callbackUrl, setCallbackUrl] = useState(null);

const getUrl = async () => {
  const url = await httpClient.getEventBrokerUrl();
  setCallbackUrl(url); 
}

// Store in global context
context.callbackUrl = await httpClient.getEventBrokerUrl();
﻿
Step 3: Making API Calls
Make your API request by passing the callback URL as a parameter, header, or elsewhere in the request.
JS
const makeRequest = async () => {

  try {
    const response = await httpClient.post('/api', data, {
      headers: {
        'Callback': callbackUrl  
      }
    });
    
    // Handle response

  } catch (error) {
    // Handle error
  }
}
const makeRequest = async () => {

  try {
    const response = await httpClient.post('/api', data, {
      headers: {
        'Callback': callbackUrl  
      }
    });
    
    // Handle response

  } catch (error) {
    // Handle error
  }
}
﻿
Step 4: Listen for SSECallbackEvent
Once a callback is received from the server, the Console will emit a custom event, SSECallBackEvent. Your application can listen to this event in your UI code and handle the data when the API response is pushed from the server.
JS
document.addEventListener(`${consoleInstance.events().SSECallBackEvent}`, (eventData) => {
  // Handle the event data
});
document.addEventListener(`${consoleInstance.events().SSECallBackEvent}`, (eventData) => {
  // Handle the event data
});
﻿
Optimize the Callback URL State
Developers can use the useEffect hook to optimize the state management and avoid unnecessary re-fetching. See the following code below:
JS
// Store callback URL in state
const [callbackUrl, setCallbackUrl] = useState(null); 

useEffect(() => {
  // Fetch latest callback URL 
  const fetchUrl = async () => {
    const url = await httpClient.getEventBrokerUrl();
    setCallbackUrl(url);
  };

  fetchUrl();
}, [callbackUrl]); 

// Only update state if URL changed
const makeRequest = async () => {
  const newUrl = await httpClient.getEventBrokerUrl();
  if (newUrl !== callbackUrl) {
    setCallbackUrl(newUrl);
    return; 
  }

  // Make API call using current callbackUrl 
};
// Store callback URL in state
const [callbackUrl, setCallbackUrl] = useState(null); 

useEffect(() => {
  // Fetch latest callback URL 
  const fetchUrl = async () => {
    const url = await httpClient.getEventBrokerUrl();
    setCallbackUrl(url);
  };

  fetchUrl();
}, [callbackUrl]); 

// Only update state if URL changed
const makeRequest = async () => {
  const newUrl = await httpClient.getEventBrokerUrl();
  if (newUrl !== callbackUrl) {
    setCallbackUrl(newUrl);
    return; 
  }

  // Make API call using current callbackUrl 
};
﻿
﻿
Example Implementation
The following example shows how to implement SSE into an application by manually calling the getEventBrokerUrl:
JS
// Import and instantiate HTTP client 
import { OS1HttpClient } from 'console/http';

const httpClient = new OS1HttpClient(consoleContext.authInitializer, BASE_URL);

// Callback URL state
const [callbackUrl, setCallbackUrl] = useState(null);

// Get initial URL 
const getUrl = async () => {
  const url = await httpClient.getEventBrokerUrl();
  setCallbackUrl(url);
}

useEffect(() => {
  getUrl();
}, []);

// Make request
const makeRequest = async () => {

  // Get updated URL
  const newUrl = await httpClient.getEventBrokerUrl();
  
  // Only update state if changed
  if (newUrl !== callbackUrl) {
    setCallbackUrl(newUrl);
    return; 
  }

  // Make API call
  const response = await httpClient.post('/api', data, {
    headers: {
      'Callback': callbackUrl
    } 
  });

}; 

// Listen for callback event
document.addEventListener(consoleContext.events.SSECallbackEvent, (event) => {
  // handle event 
});

// Initiate request
makeRequest();
// Import and instantiate HTTP client 
import { OS1HttpClient } from 'console/http';

const httpClient = new OS1HttpClient(consoleContext.authInitializer, BASE_URL);

// Callback URL state
const [callbackUrl, setCallbackUrl] = useState(null);

// Get initial URL 
const getUrl = async () => {
  const url = await httpClient.getEventBrokerUrl();
  setCallbackUrl(url);
}

useEffect(() => {
  getUrl();
}, []);

// Make request
const makeRequest = async () => {

  // Get updated URL
  const newUrl = await httpClient.getEventBrokerUrl();
  
  // Only update state if changed
  if (newUrl !== callbackUrl) {
    setCallbackUrl(newUrl);
    return; 
  }

  // Make API call
  const response = await httpClient.post('/api', data, {
    headers: {
      'Callback': callbackUrl
    } 
  });

}; 

// Listen for callback event
document.addEventListener(consoleContext.events.SSECallbackEvent, (event) => {
  // handle event 
});

// Initiate request
makeRequest();
﻿
The implementation does the following:
Imports and instantiates HTTP client
Manages callback URL state
Calls useEffect to fetch initial URL
Calls the getEventBrokerUrl before each request
Only updates the state if the URL changed
Passes the callbackUrl state in the request
Listens for SSECallbackEvent
﻿
 
Vue.JS Integration with Console UI
SSE: Data Broadcasting