Networking & Services

This section details the mutations available for managing networking and services on your Blocklet Server. You can perform actions such as configuring routing rules, managing SSL/TLS certificates, setting up webhooks, and handling notifications. For methods to retrieve networking and service data, please see the Networking & Services Queries section.
Routing Management#These mutations allow you to manage how traffic is routed to your blocklets and services.
addRoutingSite#Adds a new routing site, which is a collection of rules for a specific domain.
Parameters
input
object
required
An object containing the site details.
3 subfields
Returns
ResponseRoutingSite
object
The response object containing the newly created site.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createRoutingSite() {
  try {
    const { site } = await client.addRoutingSite({
      input: {
        domain: 'example.com',
        type: 'blocklet',
        rules: [
          {
            from: { pathPrefix: '/' },
            to: { type: 'blocklet', did: 'z8iZuf...' },
          },
        ],
      },
    });
    console.log('Routing site created:', site.id);
  } catch (error) {
    console.error('Error creating routing site:', error);
  }
}

createRoutingSite();
addDomainAlias#Adds a domain alias to an existing routing site.
Parameters
input
object
required
An object containing the alias details.
4 subfields
Returns
ResponseRoutingSite
object
The response object containing the updated site.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function addAlias(siteId) {
  try {
    const { site } = await client.addDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('Domain alias added:', site.domainAliases);
  } catch (error) {
    console.error('Error adding domain alias:', error);
  }
}

addAlias('z2as...'); // Replace with your site ID
deleteDomainAlias#Deletes a domain alias from a routing site.
Parameters
input
object
required
An object containing the details for deletion.
3 subfields
Returns
ResponseRoutingSite
object
The response object containing the updated site.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeAlias(siteId) {
  try {
    const { site } = await client.deleteDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('Domain alias removed:', site.domainAliases);
  } catch (error) {
    console.error('Error removing domain alias:', error);
  }
}

removeAlias('z2as...'); // Replace with your site ID
updateRoutingSite#Updates properties of an existing routing site, such as CORS allowed origins.
Parameters
input
object
required
An object containing the update details.
3 subfields
Returns
ResponseRoutingSite
object
The response object containing the updated site.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function updateSite(siteId) {
  try {
    const { site } = await client.updateRoutingSite({
      input: {
        id: siteId,
        corsAllowedOrigins: ['https://app.example.com'],
      },
    });
    console.log('Routing site updated:', site.id);
  } catch (error) {
    console.error('Error updating routing site:', error);
  }
}

updateSite('z2as...'); // Replace with your site ID
addRoutingRule#Adds a new routing rule to an existing site.
Parameters
input
object
required
An object containing the routing rule details.
2 subfields
Returns
ResponseRoutingSite
object
The response object containing the updated site.
2 subfields
updateRoutingRule#Updates an existing routing rule within a site.
Parameters
input
object
required
An object containing the routing rule update details.
2 subfields
Returns
ResponseRoutingSite
object
The response object containing the updated site.
2 subfields
deleteRoutingRule#Deletes a routing rule from a site.
Parameters
input
object
required
An object containing the identifiers for the rule to be deleted.
2 subfields
Returns
ResponseRoutingSite
object
The response object containing the updated site.
2 subfields
deleteRoutingSite#Deletes an entire routing site.
Parameters
input
object
required
An object containing the ID of the site to delete.
1 subfields
Returns
GeneralResponse
object
The response object indicating success or failure.
1 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteSite(siteId) {
  try {
    await client.deleteRoutingSite({ input: { id: siteId } });
    console.log('Routing site deleted successfully.');
  } catch (error) {
    console.error('Error deleting routing site:', error);
  }
}

deleteSite('z2as...'); // Replace with your site ID
takeRoutingSnapshot#Creates a snapshot of the current routing configuration, which can be used for backup or rollback purposes.
Parameters
input
object
required
An object containing snapshot options.
2 subfields
Returns
ResponseTakeRoutingSnapshot
object
The response object containing the snapshot hash.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createSnapshot() {
  try {
    const { hash } = await client.takeRoutingSnapshot({
      input: { message: 'Backup before major update' },
    });
    console.log('Routing snapshot created with hash:', hash);
  } catch (error) {
    console.error('Error creating snapshot:', error);
  }
}

createSnapshot();
Certificate Management#Manage SSL/TLS certificates for your domains.
addCertificate#Adds a custom SSL/TLS certificate to the server.
Parameters
input
object
required
An object containing the certificate details.
3 subfields
Returns
ResponseAddNginxHttpsCert
object
The response object indicating success or failure.
1 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function uploadCertificate() {
  try {
    await client.addCertificate({
      input: {
        name: 'my-example-cert',
        privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
        certificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
      },
    });
    console.log('Certificate added successfully.');
  } catch (error) {
    console.error('Error adding certificate:', error);
  }
}

uploadCertificate();
issueLetsEncryptCert#Issues a new certificate from Let's Encrypt for a specified domain.
Parameters
input
object
required
An object containing the domain and associated site information.
3 subfields
Returns
ResponseAddLetsEncryptCert
object
The response object indicating success or failure.
1 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function issueCert(domain, did, siteId) {
  try {
    await client.issueLetsEncryptCert({
      input: {
        domain: domain,
        did: did,
        siteId: siteId,
      },
    });
    console.log(`Let's Encrypt certificate issuance initiated for ${domain}.`);
  } catch (error) {
    console.error('Error issuing certificate:', error);
  }
}

issueCert('example.com', 'z8iZuf...', 'z2as...');
updateCertificate#Updates the name of an existing custom certificate.
Parameters
input
object
required
An object containing the certificate update details.
2 subfields
Returns
ResponseUpdateNginxHttpsCert
object
The response object indicating success or failure.
1 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function renameCertificate(certId) {
  try {
    await client.updateCertificate({
      input: {
        id: certId,
        name: 'new-cert-name',
      },
    });
    console.log('Certificate updated successfully.');
  } catch (error) {
    console.error('Error updating certificate:', error);
  }
}

renameCertificate('cert_xxx'); // Replace with your certificate ID
deleteCertificate#Deletes a custom SSL/TLS certificate from the server.
Parameters
input
object
required
An object containing the ID of the certificate to delete.
1 subfields
Returns
ResponseDeleteNginxHttpsCert
object
The response object indicating success or failure.
1 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeCertificate(certId) {
  try {
    await client.deleteCertificate({ input: { id: certId } });
    console.log('Certificate deleted successfully.');
  } catch (error) {
    console.error('Error deleting certificate:', error);
  }
}

removeCertificate('cert_xxx'); // Replace with your certificate ID
Webhook Management#Create and manage webhooks to receive notifications about events on your Blocklet Server.
createWebHook#Creates a new webhook sender configuration.
Parameters
input
object
required
An object containing the webhook details.
4 subfields
Returns
ResponseCreateWebHook
object
The response object containing the new webhook sender.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createWebhook() {
  try {
    const { webhook } = await client.createWebHook({
      input: {
        type: 'api',
        title: 'My Custom Webhook',
        description: 'Sends notifications to my service.',
        params: [{ name: 'url', value: 'https://myservice.com/webhook' }],
      },
    });
    console.log('Webhook created:', webhook.id);
  } catch (error) {
    console.error('Error creating webhook:', error);
  }
}

createWebhook();
deleteWebHook#Deletes an existing webhook sender.
Parameters
input
object
required
An object containing the ID of the webhook to delete.
1 subfields
Returns
ResponseDeleteWebHook
object
The response object indicating success or failure.
1 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteWebhook(webhookId) {
  try {
    await client.deleteWebHook({ input: { id: webhookId } });
    console.log('Webhook deleted successfully.');
  } catch (error) {
    console.error('Error deleting webhook:', error);
  }
}

deleteWebhook('wh_xxx'); // Replace with your webhook ID
createWebhookEndpoint#Creates a new webhook endpoint to receive events from the Blocklet Server.
Parameters
input
object
required
An object containing the webhook endpoint details.
2 subfields
Returns
ResponseCreateWebhookEndpoint
object
The response object containing the new webhook endpoint.
1 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createEndpoint() {
  try {
    const { data } = await client.createWebhookEndpoint({
      input: {
        teamDid: 'z2qa...',
        input: {
          url: 'https://myapp.com/api/webhooks',
          description: 'My application endpoint',
          enabledEvents: [{ type: 'blocklet.started', source: 'system' }],
        },
      },
    });
    console.log('Webhook endpoint created:', data.id);
  } catch (error) {
    console.error('Error creating endpoint:', error);
  }
}

createEndpoint();
updateWebhookEndpoint#Updates an existing webhook endpoint.
Parameters
input
object
required
An object containing the webhook endpoint update details.
3 subfields
Returns
ResponseUpdateWebhookEndpoint
object
The response object containing the updated webhook endpoint.
1 subfields
deleteWebhookEndpoint#Deletes a webhook endpoint.
Parameters
input
object
required
An object containing the ID of the endpoint to delete.
2 subfields
Returns
ResponseDeleteWebhookEndpoint
object
The response object containing the deleted webhook endpoint.
1 subfields
retryWebhookAttempt#Retries a failed webhook delivery attempt.
Parameters
input
object
required
An object containing the details of the attempt to retry.
4 subfields
Returns
ResponseGetWebhookAttempt
object
The response object containing the new attempt state.
1 subfields
Notification Management#Manage user notifications within the Blocklet Server.
readNotifications#Marks one or more notifications as read.
Parameters
input
object
required
An object containing the notification IDs to mark as read.
3 subfields
Returns
ResponseReadNotifications
object
The response object indicating the number of affected notifications.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsRead(notificationIds) {
  try {
    const { numAffected } = await client.readNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} notifications marked as read.`);
  } catch (error) {
    console.error('Error marking notifications as read:', error);
  }
}

markAsRead(['notif_xxx', 'notif_yyy']);
unreadNotifications#Marks one or more notifications as unread.
Parameters
input
object
required
An object containing the notification IDs to mark as unread.
3 subfields
Returns
ResponseReadNotifications
object
The response object indicating the number of affected notifications.
2 subfields
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsUnread(notificationIds) {
  try {
    const { numAffected } = await client.unreadNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} notifications marked as unread.`);
  } catch (error) {
    console.error('Error marking notifications as unread:', error);
  }
}

markAsUnread(['notif_xxx']);
This section covered mutations for networking and services. Next, you can explore mutations for managing backups and other operational tasks.
Next: Data & Operations
Learn how to perform mutations related to data management and operational tasks.
Read More
Overview

Getting Started

Authentication

API Reference

Advanced Usage

Networking & Services

Routing Management#

addRoutingSite#

addDomainAlias#

deleteDomainAlias#

updateRoutingSite#

addRoutingRule#

updateRoutingRule#

deleteRoutingRule#

deleteRoutingSite#

takeRoutingSnapshot#

Certificate Management#

addCertificate#

issueLetsEncryptCert#

updateCertificate#

deleteCertificate#

Webhook Management#

createWebHook#

deleteWebHook#

createWebhookEndpoint#

updateWebhookEndpoint#

deleteWebhookEndpoint#

retryWebhookAttempt#

Notification Management#

readNotifications#

unreadNotifications#

Next: Data & Operations

User & Access Management

Data & Operations
