Skip to content

Endpoints

Required Endpoints

To work properly, the new custom service must have endpoints in a specific format. This will allow I3HUB to know where to get the information it needs.

Prefix API

All endpoints have a prefix that the platform checks for each request. For example, if the address of the new custom service is https://test.com, the necessary endpoints will be looked for under https://test.com/api/_hub_/ (note the underscores).

Healthcheck

GET /healthcheck

This endpoint is used to check the service and "know if it's okay". The definition of what it means "to be ok" varies from service to service and is left to the programmer. Some examples can be: the application is active, the application is active and connected to the database, etc.

Healtcheck request interval

The i3hub platform may often request the health status of its services, therefore it is recommended not to put computational-intensive operations to process. For example, it is not recommended to check the "consistency" of data in the service within this endpoint, but the ability of the service to perform its function.

Here are some examples implemented in different programming languages:

In this case it is assumed that you are using Express as a framework:

// Very simple example that just checks that the endpoint is reachable. Sometimes it is the only required thing

app.use('/healthcheck', (req, res) => {
    return res.sendStatus(200);
})

In this case it is assumed that you are using Express as a framework and that you want to check that it is connected correctly with the database:

app.use('/healthcheck', (req, res) => {
    try {
        await sequelize.authenticate()
        // Everything went fine here
        return res.sendStatus(200);
    } catch (err) {
        // Since there is no connection with the database, we prefer to be seen as "not working" from the perspective of the meta platform
        console.error('Unable to connect to the database:', err)
        return res.sendStatus(500);
    }
})

In this case it is assumed that you are using Flask as a framework and that you want to check that it is connected correctly via websocket to another service:

# ... getting ws from another module

@app.route("/healthcheck", methods=["GET"])
async def health_check():
    is_connected = await ws.recv()
    if ws.connected: 
        return json.dumps({'success':True}), 200, {'ContentType':'application/json'} 
    else:
        return json.dumps({'success':False}), 500, {'ContentType':'application/json'}

Service Configuration

GET /service

This endpoint is used to return the custom service configuration object. Through this, I3HUB can understand the structure of the custom service and the activities inside it.

In this case it is assumed that you are using Express as a framework:

app.use('/service', (req, res) => {
    return res.status(200).json(serviceConfigurationObject).end();
})

In this case it is assumed that you are using Flask as a framework:

# ... getting the service_configuration_object from somewhere else

@app.route("/service", methods=["GET"])
async def service_configuration():
return json.dumps(service_configuration_object), 200, {'ContentType':'application/json'}

The object structure contains several options and needs to be discussed on a separate page. For more information, click here.

Payload Redirect

POST /payload

The purpose of this endpoint is to "inject" some information from I3HUB into the custom service. The JSON object containing such information is called payload. There are at least two ways to do this:

  • The payload is passed to the "frontend" (or web client) through the localStorage (or sessionStorage). This happens when the application needs the information only on the client side or when using Client Side Rendering (CSR).

  • The payload is passed to the "backend" (or service server) as a payload field in the body of the http request. This happens when the application needs to process the information first (or only) on the server side and then eventually render the screen or when using Server Side Rendering (SSR).

In the CSR case, the implementation can be simply copy-pasted into your own code. In the case of SSR, on the other hand, it is necessary to connect the logic of your service with this endpoint.

For more information about the payload, check here

In this case it is assumed that you are using Express as a framework:

router.post('/payload', (req, res) => {
    return res.send(`<html>
        <script>
            localStorage.setItem('payload', '${JSON.stringify(
                req.body.payload, // note: the payload is inside the request body, not the body itself
            )}');
        </script>
    </html>`)
})

In this case it is assumed that you are using Flask as a framework:

# ... getting the service_configuration_object from somewhere else

@app.route("/payload", methods=["POST"])
def payload():
    payload = request.json["payload"]
    return (
        "<html>"
        "<script>localStorage.setItem('payload', '" + payload + "');"
        "</script>"
        "</html>"
    ), 200, {'ContentType':'text/html'}

For more information on the payload structure, read here.

Back to top