Message API/docs/components/symbol-management/folders

Symbol Folders

Folder route contracts and frontend expectations for the Symbol Management module.

Routes

Use these routes to manage folder records in the symbol library.

List: load all folder records.
Create: add a new folder record.
Get by ID: load one folder when needed.
Patch: rename or update folder metadata.
Delete: remove the folder record.
Auth header: include `x-api-key` on every folders request. If you need to issue or manage that client key, see API Key Management Overview.

GET    /symbol/folders
POST   /symbol/folders
GET    /symbol/folders/:id
PATCH  /symbol/folders/:id
DELETE /symbol/folders/:id

Routes

Request Contracts

The create and update routes use a simple payload with the folder name only.

Create Folder Payload

{
  "name": "Electrical"
}

Update Folder Payload

{
  "name": "Electrical Updated"
}

Frontend Note

After create, rename, or delete, reload the folder collection so the client stays aligned with backend uniqueness and validation rules.

Unique names: duplicate folder names should be blocked by the backend.
Protected reads and writes: send the same `x-api-key` header for list, create, update, and delete calls.
Refresh after write: do not patch the UI optimistically unless you also handle server rejections cleanly.
Dependent requests: if a deleted folder ID is still referenced by the client, clear or replace that reference before loading symbols again.

Example API Calls

Use small service functions like these from your client application, hooks, or state store.

Shared Types

const API_BASE_URL = 'http://localhost:5203/api'

type SymbolFolder = {
  id: number
  name: string
}

Get Folders

async function getFolders(): Promise<SymbolFolder[]> {
  const response = await fetch(`${API_BASE_URL}/symbol/folders`, {
    headers: {
      'x-api-key': CLIENT_API_KEY,
    },
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }

  return response.json()
}

Create Folder

async function createFolder(name: string): Promise<SymbolFolder> {
  const response = await fetch(`${API_BASE_URL}/symbol/folders`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
    body: JSON.stringify({ name }),
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }

  return response.json()
}

Update Folder

async function updateFolder(id: number, name: string): Promise<SymbolFolder> {
  const response = await fetch(`${API_BASE_URL}/symbol/folders/${id}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
    body: JSON.stringify({ name }),
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }

  return response.json()
}

Delete Folder

async function deleteFolder(id: number): Promise<void> {
  const response = await fetch(`${API_BASE_URL}/symbol/folders/${id}`, {
    method: 'DELETE',
    headers: {
      'x-api-key': CLIENT_API_KEY,
    },
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }
}