Skip to main content

HTTP API

SAGE3 employs a RESTful API for communication between the client and server. The API is built using Express routers. The API is split into two parts, the public and protected API. The public API is accessible to anyone, while the private API requires a valid login or a JWT token to access.

  • Public API
    • Info: Provides generic information about the SAGE3 server.
    • Time: Provides the current server time since epoch.
    • Files: Download a file asset using a UUID token
  • Protected API
    • Collections: users, assets, apps, boards, rooms, presence, message, plugins,
    • Misc: configuration, nlp

Info​

Provides generic information about the SAGE3 server.

/api/info​

  • Method: GET
  • Request
    • No fields required
  • Response:
    • Body: 
      {
        "serverName": "Chicago",
        "port": 443,
        "production": true,
        "version": "1.0.0-beta.2",
        "logins": ["google", "cilogon", "guest", "jwt"],
        "isSage3": true
      }
      • serverName (string): The name of the server.
      • port (number): The port the server is running on.
      • production (boolean): Is this server a production or development server?
      • version (string): The version of the SAGE3 server code this server is running.
      • logins (string[]): The enabled login strategies this server is running. Ex. ("guest" | "google" | "cilogon" | "jwt")
      • isSage3 (boolean): Is this a sage3 server? Used to verify if URL is a SAGE3 server incase you need to check before accessing.

Configuration​

Provides generic information about the SAGE3 server, but unlike the info endpoint this requires credentials since it provides more information.

/api/configuration​

  • Method: GET
  • Request
    • credentials: Required
  • Response:
    • Body: 
      {
        "serverName": "Chicago",
        "port": 443,
        "production": true,
        "version": "1.0.0-beta.2",
        "logins": ["google", "cilogon", "guest", "jwt"],
        "isSage3": true,
        "namespace": "f44c0a66-f1d4-454a-b1ca-00a49782bc27",
        "token": "79602da798f32f1e",
        "admins": ["johedoe@gmail.com"]
      }
      • serverName (string): The name of the server.
      • port (number): The port the server is running on.
      • production (boolean): Is this server a production or development server?
      • version (string): The version of the SAGE3 server code this server is running.
      • logins (string[]): The enabled login strategies this server is running. Ex. ("guest" | "google" | "cilogon" | "jwt")
      • isSage3 (boolean): Is this a sage3 server? Used to verify if URL is a SAGE3 server incase you need to check before accessing.
      • namespace (string): Namespace for signing uuid v5 keys.
      • token (string): Token to access JupyterLab.
      • admins (string[]): Array of user's who have admin rights. (emails)

Time​

Provides the current server time since epoch.

/api/time​

  • Method: GET

  • Request

    • No fields required

  • Response:

    • Body:

      {
        "epoch": 1680641516527
      }
      • epoch (number): The Server's current time since epoch. (ms)

Files​

Acccess a file from the server's asset collection using the asset's ID and a UUIDv5 token. This route is used to make an asset publicly accessible: the developer computes a UUIDv5 token using the asset's ID and a secret key (SAGE3's namespace), and then the client can access the asset using the ID and the token.

/api/files/:id/:token​

  • Method: GET
  • Route
    • id: The id of the file.
    • token: A UUIDv5 token.
  • Request
    • No fields required
  • Response:
    • Status: 200
    • Response: The file requested.

Collections​

The various collections within SAGE3.

The SBDocument is the Document within the actual database collections. Documents are just JSON objects with the following structure:

type SBDocument = {
  _id: string;
  _createdAt: number;
  _createdBy: string;
  _updatedAt: number;
  _updatedBy: string;
  // Type refers to the application specific data type, which extends SBJSON
  data: Type;
};

The various collections have their own types and are on the data property.

Applications​

The applications collection contains all of the server's open applications. Opened applications are apps that are currently visiable on a board somewhere.

type AppSchema = {
  title: string;
  roomId: string;
  boardId: string;
  position: { x: number; y: number; z: number };
  size: { width: number; height: number; depth: number };
  rotation: { x: number; y: number; z: number };
  type: AppName; // Application name: Counter, Stickie, ...
  state: AppState; // Application-specific data type
  raised: boolean;
};

/api/apps​

Creates one or more applications (batch mode).

  • Method: POST
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    • body: AppSchema or {"batch": AppSchema[]}
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully created documents.",
        "data": [
          {
            "_id": "5cbfca4c-3636-47a7-a368-57ebe7443818",
            "_createdAt": 1680553407429,
            "_createdBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "_updatedAt": 1680553407429,
            "_updatedBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "data": {
              "title": "A Counting App",
              "roomId": "ec3dcbe8-8e0f-4fa8-89e1-b8c9663eae64",
              "boardId": "678c900a-e9fd-4448-b370-84aed6bf3766",
              "position": { "x": 0, "y": 0, "z": 0 },
              "size": { "width": 300, "height": 300, "depth": 0 },
              "position": { "x": 0, "y": 0, "z": 0 },
              "type": "Counter",
              "state": { "count": 42 },
              "raised": true
            }
          }
        ]
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (SBDocument<AppSchema>[] | undefined): An array of the newly added documents. In the above example we are showing a Counter app with its state set to: {"count": 42}. If the request was unsuccesful then this will be undefined.

/api/apps​

Returns all of the applications, or a selection of applications (batch mode).

  • Method: GET
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    • body: Not Required or {"batch": string[]}
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully retrieved the documents.",
        "data": [
          {
            "_id": "5cbfca4c-3636-47a7-a368-57ebe7443818",
            "_createdAt": 1680553407429,
            "_createdBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "_updatedAt": 1680553407429,
            "_updatedBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "data": {
              "title": "A Counting App",
              "roomId": "ec3dcbe8-8e0f-4fa8-89e1-b8c9663eae64",
              "boardId": "678c900a-e9fd-4448-b370-84aed6bf3766",
              "position": { "x": 0, "y": 0, "z": 0 },
              "size": { "width": 300, "height": 300, "depth": 0 },
              "position": { "x": 0, "y": 0, "z": 0 },
              "type": "Counter",
              "state": { "count": 42 },
              "raised": true
            }
          }
        ]
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (SBDocument<AppSchema>[] | undefined): An array of the requested documents. If the request was unsuccesful then this will be undefined.

/api/apps/:id​

Returns a single application.

  • Method: GET
  • Route
    • id: The id of the document you are requesting.
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully retrieved the document.",
        "data": [
          {
            "_id": "5cbfca4c-3636-47a7-a368-57ebe7443818",
            "_createdAt": 1680553407429,
            "_createdBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "_updatedAt": 1680553407429,
            "_updatedBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "data": {
              "title": "A Counting App",
              "roomId": "ec3dcbe8-8e0f-4fa8-89e1-b8c9663eae64",
              "boardId": "678c900a-e9fd-4448-b370-84aed6bf3766",
              "position": { "x": 0, "y": 0, "z": 0 },
              "size": { "width": 300, "height": 300, "depth": 0 },
              "position": { "x": 0, "y": 0, "z": 0 },
              "type": "Counter",
              "state": { "count": 42 },
              "raised": true
            }
          }
        ]
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (SBDocument<AppSchema>[] | undefined): An array of the requested documents. If the request was unsuccesful then this will be undefined.

/api/apps/?query=xyz​

Returns a selection of applications based on the room, board or type.

  • Method: GET
  • Route
    • query: roomId | boardId | type
    • type referes to the application type (e.g. Counter, Stickie, etc).
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully retrieved documents.",
        "data": [
          {
            "_id": "5cbfca4c-3636-47a7-a368-57ebe7443818",
            "_createdAt": 1680553407429,
            "_createdBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "_updatedAt": 1680553407429,
            "_updatedBy": "d725ada3-cb66-4536-aef0-186f0dcae6ab",
            "data": {
              "title": "A Counting App",
              "roomId": "ec3dcbe8-8e0f-4fa8-89e1-b8c9663eae64",
              "boardId": "678c900a-e9fd-4448-b370-84aed6bf3766",
              "position": { "x": 0, "y": 0, "z": 0 },
              "size": { "width": 300, "height": 300, "depth": 0 },
              "position": { "x": 0, "y": 0, "z": 0 },
              "type": "Counter",
              "state": { "count": 42 },
              "raised": true
            }
          }
        ]
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (SBDocument<AppSchema>[] | undefined): An array of the requested documents. If the request was unsuccesful then this will be undefined.

/api/apps​

Modify a series of applications (batch mode).

  • Method: PUT
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    • body: {"batch": {id: string, update: AppSchema}[]}
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully updated documents.",
        "data": true
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (boolean): True if the update was successfull.

/api/apps/:id​

Modify one single application.

  • Method: PUT
  • Route
    • id: The id of the document to update.
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    • body: AppSchema
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully updated the document.",
        "data": true
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (boolean): True if the update was successfull.

/api/apps​

Delete a series of applications (batch mode).

  • Method: DELETE
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    • body: {"batch": string[]}
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully retrieved the documents.",
        "data": true
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (boolean): If the delete was successfull.

/api/apps/:id

Delete one application.

  • Method: DELETE
  • Route
    • id: The id of the document to delete.
  • Request
    • credentials: Required
    • headers: 
      {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
  • Response:
    • Status: 200 | 500
    • Body: 
      {
        "success": true,
        "message": "Successfully retrieved the documents.",
        "data": true
      }
      • success (boolean): True if the request was successful.
      • message (string): A message about requests success or failure.
      • data (boolean): If the delete was successfull.