How to Use RMF-Web API Server and API Client for Custom Frontend Integration (#635)

Open-RMF Open-RMF General
1

Posted by @Oussama-Dallali99:

Hello everyone,

I am working on integrating custom Robots-control Front-end into rmf-web. I have developed my own frontend, which replicates most of the features of the rmf-web-dashboard. Now, I need guidance on how to use the api-server and api-client from rmf-web to fetch data and send commands to Open-RMF.

Here are my specific questions

API Server Setup: How can I configure and run the api-server to connect it with Open-RMF? Should I use Docker or set up a custom configuration file?

API Client Usage: What is the best way to use the api-client library to subscribe to topics (e.g., robot states, task updates) and send commands (e.g., task submissions)?

Custom Frontend Integration: Are there any specific considerations for connecting a custom frontend with Open-RMF using these tools?

I have seen examples like using socket.io-client for subscribing to topics (door_states, etc.) and emitting events, but I am looking for a clear workflow or best practices for implementing this in my project.

Any advice or resources would be greatly appreciated!

Thank you!

Edited by @Oussama-Dallali99 at 2025-03-12T01:54:47Z

2

Posted by @aaronchongth:

Hi @Oussama-Dallali99! That’s awesome to hear.

The API server operates mostly using REST, but there are socket.io endpoints for some reactive updates (states, etc) as you mentioned. Once you have the API server up and running, you can check out the endpoints at http://localhost:8000/docs, assuming you are running the server locally and following the README instructions

API Server Setup: How can I configure and run the api-server to connect it with Open-RMF? Should I use Docker or set up a custom configuration file?

This is up to the user, and use-case. We have a deployment template showing how we can set up the API server in a kubernetes cluster alongside an Open-RMF deployment, GitHub - open-rmf/rmf_deployment_template: This repo provides a template to deploy RMF. In this template, we do set up a custom configuration file, rmf_deployment_template/charts/rmf-deployment/templates/config/rmf-web-rmf-server-configmap.yaml at main · open-rmf/rmf_deployment_template · GitHub

Do take note that this deployment template is a template, and is only for reference, and may not reflect what a production deployment should or should not look like

API Client Usage: What is the best way to use the api-client library to subscribe to topics (e.g., robot states, task updates) and send commands (e.g., task submissions)?

Check out the docs here, rmf-web/packages/rmf-dashboard-framework/docs/getting-started.md at main · open-rmf/rmf-web · GitHub, where users can create/modify their own dashboard by using rmf-dashboard-framework as a built library. By extension, this applies to the api-client library too.

Custom Frontend Integration: Are there any specific considerations for connecting a custom frontend with Open-RMF using these tools?

I assume these tools mean the overall architecture of Open-RMF deployments communicating with an API server over ROS 2 and websockets, using an ORM with databases, and with a separate dashboard app. With ROS 2 being one the communication protocols between the API server and Open-RMF, using these tools will require them to be running on the same machine, or in the same cluster, if not, have a way to properly pipe DDS messages across clusters/setups.

I’d say specific considerations would be entirely up to the user and user’s requirements. The architecture we chose like all other architectures, have their pros and cons, and this was the one that fit our use cases in the past. Users are encouraged to make the system design decisions that is best suited for their use-case.

3

Posted by @Oussama-Dallali99:

I’ve been testing data retrieval from the /fleets endpoint using a simple fetch-based script (see snippet below). For testing purposes I’m ignoring authentication. My main question is:

For a large-scale project, is directly fetching and processing data like this the best approach, or should I use the provided api-client library? Also, what best practices would you recommend for efficiently fetching and handling this data at scale?

async function fetchAllRobotAttributes() { const response = await fetch('http://localhost:8000/fleets'); if (!response.ok) throw new Error(HTTP error! status: ${response.status}`);
const data = await response.json();
// Process and return robot attributes here
return data;
}

fetchAllRobotAttributes()
.then(data => console.log(‘Data fetched:’, data))
.catch(error => console.error(‘Error:’, error));
`

Thanks for any insights!

4

Posted by @aaronchongth:

Awesome!

I’d say it depends on the functionality expected, the provided API client library is mostly generated automatically with OpenAPI, however the library does come with support for socket.io routes, that users can “subscribe” to new changes to certain data, for example door states, lift states

Also, what best practices would you recommend for efficiently fetching and handling this data at scale?

This will also depend on the types of data expected to be retrieved. Most of the data models are small enough to be handled at scale without issues, however we’ve recently had chats with the community that for extremely long running robot tasks or if a robot is stuck waiting for a long period of time while performing a task, a task state message can get quite large, and if that is updated and queried at scale, the current API server will not be able to handle the data model parsing.

Some things to keep in mind, the API server is designed and built with the intention to support 1 Open-RMF deployment, at the scale of a single facility, or building, but nothing is stopping users from testing it’s limits. It’s written in python so it’s just a single process, hence there will be a bottleneck at some point eventually.

I’d say depending on your use-case, you might need to either define what “scale” means and if it is better to set up individual API servers for each deployment and have a data aggregation layer that pulls data from each API server instead.

5

Posted by @Oussama-Dallali99:

Thanks for the detailed context! :folded_hands: I have a follow-up question regarding my implementation strategy. Currently, I’m using my custom Socket.IO setup for handling fleet state updates (i.e. /fleets/tinyRobot/state). Given that, should I continue creating these scripts from scratch, or is there a way to use the built-in RMF API client that I can leverage for subscription management?

I’d appreciate it if you could point me to any documentation or examples regarding the API client’s subscription patterns.

Below is my current Socket.IO implementation for reference:

import { io } from "socket.io-client";

// Replace with your server's Socket.IO endpoint
const SERVER_URL = 'http://127.0.0.1:8000';  


const AUTH_TOKEN = "your_secure_token_here"; 

const socket = io(SERVER_URL, {
  auth: {
    token: AUTH_TOKEN,
  },
  path: '/socket.io',  
  transports: ['polling'] 
});

socket.on('connect', () => {
  console.log('Connected to the server.');
  const roomName = '/fleets/tinyRobot/state';
  socket.emit('subscribe', { room: roomName }, (response) => {
    if (response && response.error) {
      console.error('Subscription error:', response.error);
    } else {
      console.log(`Subscribed to room: ${roomName}`);
    }
  });
});

socket.on('/fleets/tinyRobot/state', (data) => {
  console.log('Fleet status update:', data);
});

socket.on('disconnect', () => {
  console.log('Disconnected from the server.');
});

socket.on('connect_error', (err) => {
  console.error('Connection error:', err.message);
});

socket.on('error', (err) => {
  console.error('Socket error:', err);
});
6

Posted by @aaronchongth:

The subscriptions are handled here, rmf-web/packages/api-client/lib/index.ts at main · open-rmf/rmf-web · GitHub, linking just in case. You can definitely use the built-in subscriptions in the api-client.

Again, it will depend on your use-case and project, especially since the api-client is just a source library at the moment and not released, as well as built and generated with the current source API server version. I won’t be able to advice much unfortunately, however ideally you’d re-use what’s already in rmf-web, and if changes or features are needed, you can start a pull request