Rasterex API/docs/components/symbol-management/symbols

Symbols

Upload payloads and symbol record contracts for the Symbol Management module.

Routes

Use these routes to manage symbol records within a folder.

List by folder: load all symbol records for a folder ID.
Create: add a new symbol under the active folder.
Get by ID: open detailed symbol information.
Patch: update metadata, content, or move the symbol to another folder.
Delete: remove the symbol record.
Auth header: include x-api-key on every symbols request. If you need to issue or manage that client key, see API Key Management Overview.

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

Routes

Request Contracts

The module stores uploaded file information inside the data field as a JSON string containing file metadata and base64 content.

For readability, document the inner data object separately and then show the final payload using JSON.stringify(...).

Serialized Data Structure

{
  name: 'valve.png',
  type: 'image/png',
  content: '<base64>',
  width: 120,
  height: 80,
}

Create Symbol Payload

{
  name: 'Valve',
  type: 'image/png',
  data: JSON.stringify({
    name: 'valve.png',
    type: 'image/png',
    content: '<base64>',
    width: 120,
    height: 80,
  }),
}

Update Symbol Payload

{
  name: 'Valve Updated',
  type: 'image/png',
  data: JSON.stringify({
    name: 'valve.png',
    type: 'image/png',
    content: '<base64>',
    width: 120,
    height: 80,
  }),
  folderId: 3,
}

Upload Note

The user selects a file from the computer, the frontend reads it, extracts base64 content, measures the image dimensions, and serializes that data into the data string.

Use the file name without extension for the symbol name, and use the uploaded MIME type for type.

Preview source: a client can generate a local data URL before save if preview support is needed.
Stored contract: the backend receives the serialized JSON string, not the raw data URL.
Protected uploads: the same x-api-key header is required for list, create, update, and delete requests.
Folder refresh: after create, update, move, or delete, reload the active folder symbols list.

Example API Calls

These examples show request functions you can call from a client application after a file is prepared for upload.

Shared Types

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

type SymbolFileData = {
  name: string
  type: string
  content: string
  width: number
  height: number
}

type SymbolRecord = {
  id: number
  name: string
  type: string
  data: string
  folderId: number
}

Get Symbols

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

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

  return response.json()
}

Create Symbol

async function createSymbol(
  folderId: number,
  payload: {
    name: string
    type: string
    data: SymbolFileData
  }
): Promise<SymbolRecord> {
  const response = await fetch(`${API_BASE_URL}/symbol/folders/${folderId}/symbols`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
    body: JSON.stringify({
      name: payload.name,
      type: payload.type,
      data: JSON.stringify(payload.data),
    }),
  })

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

  return response.json()
}

Update Symbol

async function updateSymbol(
  id: number,
  payload: {
    name: string
    type: string
    data: SymbolFileData
    folderId: number
  }
): Promise<SymbolRecord> {
  const response = await fetch(`${API_BASE_URL}/symbol/symbols/${id}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
    body: JSON.stringify({
      name: payload.name,
      type: payload.type,
      data: JSON.stringify(payload.data),
      folderId: payload.folderId,
    }),
  })

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

  return response.json()
}

Delete Symbol

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

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