Zabbix GraphQL API

A GraphQL wrapper for the Zabbix API that provides enhanced mass import/export operations, hierarchical host group management, and dynamic schema extensibility. Built with Apollo Server, TypeScript, and ES modules.

🚀 Features

• GraphQL Interface: Modern GraphQL API wrapping Zabbix functionality

  • Reference: schema/queries.graphql, schema/mutations.graphql, src/api/start.ts

• Hierarchical Data Mapping: Automatic mapping of Zabbix items/tags to nested GraphQL objects

  • Reference: src/api/resolver_helpers.ts, schema/device_value_commons.graphql, docs/sample_all_devices_query.graphql

• Mass Operations: Import/export capabilities for hosts, templates, and user rights

  • Reference: schema/mutations.graphql (importHosts, importTemplates, importUserRights, etc.), docs/sample_import_*.graphql

• Dynamic Schema Extension: Extend the schema without code changes using environment variables

  • Reference: src/api/schema.ts, schema/extensions/, src/common_utils.ts (ADDITIONAL_SCHEMAS, ADDITIONAL_RESOLVERS)

• Permission System: Role-based access control using Zabbix template groups

  • Reference: schema/api_commons.graphql (Permission enum, PermissionRequest), src/api/resolvers.ts (hasPermissions, userPermissions), docs/sample_import_permissions_template_groups_mutation.graphql

• Real-time Subscriptions: WebSocket support for GraphQL subscriptions (infrastructure implemented)

  • Reference: src/api/start.ts (WebSocketServer integration with graphql-ws), AGENTS.md (mentions WebSocket support), package.json (graphql-ws, subscriptions dependencies)

• Type Safety: Full TypeScript support with generated types

  • Reference: codegen.ts, src/schema/generated/graphql.ts, tsconfig.json, package.json (devDependencies for GraphQL Codegen)

📋 Prerequisites

Before you begin, ensure you have met the following requirements:

• Node.js >= 18.x (tested with v21.5.0)
• NPM >= 8.x
• Zabbix Server with API access
• Zabbix Super Admin Token (for full functionality)

🛠️ Installation

Clone the repository

git clone https://github.com/your-repo/zabbix-graphql-api.git
cd zabbix-graphql-api

Install dependencies

npm install

⚙️ Configuration

Environment Variables

Create a .env file in the project root with the following variables:

# Zabbix connection
ZABBIX_BASE_URL=http://your-zabbix-server/zabbix
ZABBIX_AUTH_TOKEN=your-super-admin-token
ZABBIX_AUTH_TOKEN_FOR_REQUESTS=your-super-admin-token

# Optional configuration
ZABBIX_EDGE_DEVICE_BASE_GROUP=Roadwork
ZABBIX_ROADWORK_BASE_GROUP=Roadwork
ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX=Permissions
SCHEMA_PATH=./schema/

# Dynamic schema extension (optional)
ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql
ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice

# Logging
LOG_LEVELS=info

Environment Variable Details

Variable	Description	Default
ZABBIX_BASE_URL	URL to your Zabbix server (include /zabbix path)	-
ZABBIX_AUTH_TOKEN	Zabbix Super Admin API token	-
ZABBIX_AUTH_TOKEN_FOR_REQUESTS	Token used for automated requests	-
ZABBIX_EDGE_DEVICE_BASE_GROUP	Base group for edge devices	-
ZABBIX_ROADWORK_BASE_GROUP	Base group for roadwork devices	-
ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX	Prefix for permission template groups	Permissions
SCHEMA_PATH	Path to schema files	./schema/
ADDITIONAL_SCHEMAS	Comma-separated list of additional schema files	-
ADDITIONAL_RESOLVERS	Comma-separated list of resolver types to generate	-
LOG_LEVELS	Log level configuration	-

▶️ Running the Application

Development Mode

# Start with hot reloading
npm run start

The GraphQL API will be available at http://localhost:4000/

Available Queries and Mutations after start

Queries

• apiVersion - Returns the API build version
• zabbixVersion - Returns the version of the connected Zabbix instance
• login - Authenticates with Zabbix and returns an authentication token
• logout - Logs out from Zabbix, invalidating the current session
• allHosts - Returns all hosts and their items
• allDevices - Returns all devices and their items (hosts with deviceType)
• allHostGroups - Returns all host groups
• locations - Returns all locations used by hosts
• exportHostValueHistory - Exports value history for Zabbix items
• userPermissions - Returns all user permissions
• hasPermissions - Checks if the current user has requested permissions
• exportUserRights - Exports user rights (roles and groups)
• templates - Returns templates
• allTemplateGroups - Returns all template groups

Mutations

• createHost - Creates a single host in Zabbix
• importHostGroups - Mass import Zabbix host groups
• importHosts - Mass import hosts and assign them to host groups
• importUserRights - Import user rights (roles and groups) into Zabbix
• importTemplateGroups - Mass import template groups
• importTemplates - Mass import templates
• deleteTemplates - Delete templates by their IDs or by a name pattern
• deleteTemplateGroups - Delete template groups by their IDs or by a name pattern

Production Build

# Compile TypeScript
npm run compile

# Run production build
npm run prod

Available Scripts

Script	Description
npm run start	Start development server with hot reload
npm run compile	Compile TypeScript to JavaScript
npm run prod	Run production build
npm run test	Run tests
npm run codegen	Generate TypeScript types from GraphQL schema
npm run nodemon	Alternative development runner

🐳 Docker Deployment

Using Pre-built Images

The application can be deployed using Docker:

# Build the image
docker build -t zabbix-graphql-api .

# Run the container
docker run -d \
  --name zabbix-graphql \
  -p 4000:4000 \
  -e ZABBIX_BASE_URL=http://your-zabbix-server/zabbix \
  -e ZABBIX_AUTH_TOKEN=your-super-admin-token \
  zabbix-graphql-api

Building Your Own Image

# Build with custom API version
docker build --build-arg API_VERSION=v1.0.0 -t zabbix-graphql-api .

# Run with environment file
docker run -d \
  --name zabbix-graphql \
  -p 4000:4000 \
  --env-file .env \
  zabbix-graphql-api

🔐 Roles and Permissions Extension

The API implements a permission system using Zabbix template groups:

Permission Template Groups

• Template groups with prefix Permissions/ (configurable via ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX) are used for permissions
• Users gain permissions by being assigned to user groups that have access to these permission template groups

Available Permissions

The system supports three permission levels defined in schema/api_commons.graphql:

• DENY: Explicitly denies access (supersedes other permissions)
• READ: Allows viewing/reading access
• READ_WRITE: Allows both reading and writing (implies READ permission)

Permission Object Names

Permission object names map to Zabbix template group paths: Permissions/{objectName}

GraphQL Permission Queries

# Check if current user has specific permissions
query HasPermissions {
  hasPermissions(permissions: [
    { objectName: "hosts", permission: READ },
    { objectName: "templates", permission: READ_WRITE }
  ])
}

# Get all user permissions
query GetUserPermissions {
  userPermissions(objectNames: ["hosts", "templates"])
}

Setting Up Permissions

1. Create template groups with the prefix Permissions/ (e.g., Permissions/hosts, Permissions/templates)
2. Assign these template groups to user groups in Zabbix with appropriate permission levels
3. Users in those user groups will inherit the permissions

Detailed Permission Usage Examples

For comprehensive examples of permission usage patterns, see schema/api_commons.graphql which contains detailed documentation in the PermissionRequest input type comments, including real-world examples of how to model permissions for buttons, status controls, and application features.

See also docs/sample_import_permissions_template_groups_mutation.graphql for examples of importing permission template groups.

📊 Schema and Schema Extension

Main Schema Structure

The GraphQL schema is located in the schema/ directory and consists of:

• queries.graphql - Query definitions (see detailed documentation in file comments)
• mutations.graphql - Mutation definitions (see detailed documentation in file comments)
• devices.graphql - Device-related types (see detailed documentation in file comments)
• zabbix.graphql - Zabbix-specific types (see detailed documentation in file comments)
• device_value_commons.graphql - Common value types (see detailed documentation in file comments)
• api_commons.graphql - Common API types and permission system (see detailed documentation in file comments)
• extensions/ - Custom device type extensions

For comprehensive understanding of each operation, read the detailed comments in the respective schema files.

Dynamic Schema Extension

Extend the schema without code changes using environment variables:

ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql
ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice

This enables runtime schema extension for custom device types without modifying the core code.

Sample Operations

For practical examples of schema usage, see the sample files in the docs/ directory:

• docs/sample_all_devices_query.graphql - Example of querying all devices
• docs/sample_import_templates_mutation.graphql - Example of importing templates
• docs/sample_import_host_groups_mutation.graphql - Example of importing host groups

🗂️ Hierarchical Data Mapping

The API automatically maps Zabbix items to nested GraphQL objects using the createHierarchicalValueFieldResolver function:

• Zabbix item key state.current.values.temperature → GraphQL { state: { current: { values: { temperature } } } }
• Type hints: json_, str_, bool_, float_ prefixes for value conversion
• Automatic resolution of hierarchical structures from flat Zabbix item keys

The createHierarchicalValueFieldResolver function (found in src/api/resolver_helpers.ts) dynamically creates resolvers that map Zabbix items or tags to hierarchical GraphQL structures. It uses field names and Zabbix item keys (dot-separated) to automatically resolve nested objects, eliminating the need for manual resolver definitions for each hierarchical field.

For detailed information about the mapping mechanism and type hinting, see the comments in schema/device_value_commons.graphql and src/api/resolver_helpers.ts.

See docs/sample_all_devices_query.graphql for examples of how hierarchical data appears in query results.

🏷️ Zabbix Tags Usage

Zabbix tags are used for:

• Device classification (deviceType tag)
• Host categorization (hostType tag)
• Custom metadata storage
• Permission assignment through template groups

For detailed information about tag usage and available tag types, see the comments in schema/devices.graphql and schema/zabbix.graphql.

See docs/sample_all_hosts_query.graphql and docs/sample_all_devices_query.graphql for examples of how tags appear in query results.

🧪 Testing

Run the test suite:

npm test

The testing strategy includes:

• Unit tests with mocked Zabbix API responses
• Integration tests with real GraphQL operations
• Permission system validation
• Import/export functionality testing

📖 Detailed Documentation Through Comments

This project uses extensive inline documentation in the form of comments within the GraphQL schema files and documentation samples. For the most comprehensive understanding of the API, its capabilities, and usage patterns, read the detailed comments in:

• schema/queries.graphql - Complete documentation of all query operations
• schema/mutations.graphql - Complete documentation of all mutation operations with usage examples
• schema/api_commons.graphql - Detailed explanation of the permission system with real-world usage examples
• docs/*.graphql - Practical examples of all operations with sample variables and expected outcomes

The comments in these files contain real-world usage examples, implementation notes, and detailed explanations that go beyond what's covered in this README.

📖 Example: Extending Schema with Distance Tracker Device

Zabbix-Side Configuration

Before extending the schema, you need to configure Zabbix appropriately:

1. Host Configuration in Zabbix

• Create a host in Zabbix with the tag deviceType set to distance-tracker
• Add items to the host with hierarchical keys that match your GraphQL fields:
  • distance.current (for the distance field)
  • battery.level (for the batteryLevel field)
  • status.lastSeen (for the lastSeen field)
  • location.latitude and location.longitude (for the location object)

2. Item Key Naming Convention

The API automatically maps dotted item keys to nested GraphQL objects:

• Zabbix item key distance.current → GraphQL { distance }
• Zabbix item key battery.level → GraphQL { batteryLevel }
• Zabbix item key location.latitude → GraphQL { location: { location_lat } }

Schema Extension Steps

1. Create Schema Extension

Create schema/extensions/distance_tracker_device.graphql:

type DistanceTrackerDevice {
  id: String
  name: String
  location: Location
  distance: Float
  batteryLevel: Float
  lastSeen: DateTime
}

2. Configure Environment Variables

ADDITIONAL_SCHEMAS=./schema/extensions/distance_tracker_device.graphql
ADDITIONAL_RESOLVERS=DistanceTrackerDevice

3. Import Template via GraphQL Mutation

Instead of manually creating items in Zabbix, you can import a complete template using the GraphQL API:

mutation ImportDistanceTrackerTemplate($templates: [CreateTemplate!]!) {
  importTemplates(templates: $templates) {
    host
    templateid
    message
    error {
      message
      code
      data
    }
  }
}

Variables:

{
  "templates": [
    {
      "host": "DISTANCE_TRACKER",
      "name": "Distance Tracker Device Template",
      "groupNames": ["Templates/Roadwork/Devices"],
      "tags": [
        { "tag": "deviceType", "value": "DistanceTrackerDevice" }
      ],
      "items": [
        {
          "name": "Distance Current Value",
          "type": 0,
          "key": "distance.current",
          "value_type": 0,
          "history": "7d",
          "units": "m"
        },
        {
          "name": "Battery Level",
          "type": 0,
          "key": "battery.level",
          "value_type": 0,
          "history": "7d",
          "units": "%"
        },
        {
          "name": "Last Seen Timestamp",
          "type": 0,
          "key": "status.lastSeen",
          "value_type": 4,
          "history": "30d"
        },
        {
          "name": "Location Latitude",
          "type": 0,
          "key": "location.latitude",
          "value_type": 0,
          "history": "30d",
          "units": "deg"
        },
        {
          "name": "Location Longitude",
          "type": 0,
          "key": "location.longitude",
          "value_type": 0,
          "history": "30d",
          "units": "deg"
        }
      ]
    }
  ]
}

This creates a template in Zabbix with all the required items that map to your GraphQL fields.

4. Link Hosts to the Template

After importing the template, link your hosts to it in Zabbix or via the importHosts mutation:

mutation ImportHosts($hosts: [CreateHost!]!) {
  importHosts(hosts: $hosts) {
    deviceKey
    hostid
    message
    error {
      message
      code
      data
    }
  }
}

Variables:

{
  "hosts": [
    {
      "deviceKey": "DistanceTracker001",
      "name": "Distance Tracker 001",
      "deviceType": "distance-tracker",
      "groupNames": ["Roadwork/Devices"],
      "templateids": [12345]  // Use the templateid returned from importTemplates
    }
  ]
}

5. Use in Queries

Once the template and host are set up in Zabbix, query the data via GraphQL:

query GetDistanceTrackers {
  allDevices(tag_deviceType: ["distance-tracker"]) {
    ... on DistanceTrackerDevice {
      id
      name
      location {
        name
        location_lat
        location_lon
      }
      distance
      batteryLevel
      lastSeen
    }
  }
}

6. Expected Response Structure

Based on the Zabbix configuration above, the API will return:

{
  "data": {
    "allDevices": [
      {
        "id": "12345",
        "name": "Distance Tracker 001",
        "location": {
          "name": "Main Office",
          "location_lat": "37.7749",
          "location_lon": "-122.4194"
        },
        "distance": 42.5,
        "batteryLevel": 87.2,
        "lastSeen": "2023-10-15T10:30:00Z"
      }
    ]
  }
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

📚 Schema and Documentation

Schema Files as Documentation

The schema files in the schema/ directory serve as both API definition and documentation. Each type, field, and operation includes detailed comments explaining usage, parameters, and examples. For comprehensive understanding of the API, read the comments in:

• schema/queries.graphql - Query operations with detailed parameter descriptions
• schema/mutations.graphql - Mutation operations with input type documentation
• schema/api_commons.graphql - Common types and permission system documentation
• schema/devices.graphql - Device-related types and hierarchies
• schema/zabbix.graphql - Zabbix-specific mappings and types

Documentation Files

The docs/ directory contains sample GraphQL queries and mutations that demonstrate how to use the API:

• sample_all_*.graphql - Sample queries for retrieving hosts, devices, templates, and groups
• sample_import_*.graphql - Sample mutations for importing various Zabbix entities
• sample_delete_*.graphql - Sample mutations for deleting templates and template groups
• sample_export_*.graphql - Sample queries for exporting user rights and other data
• VCR - Technical product information.pdf - Technical documentation for specific implementations

Of particular interest:

• sample_import_distance_tracker_template.graphql - Complete example of importing a template for distance tracker devices
• sample_import_user_rights_mutation.graphql - Example of importing user permissions
• sample_import_permissions_template_groups_mutation.graphql - Example of importing permission template groups

Reading Comments for Detailed Documentation

For detailed documentation with usage examples and implementation notes, read the comments in the schema and documentation files. The project creator has embedded extensive documentation as comments in the GraphQL schema files, which provide real-world usage examples and implementation guidance that complement this README.

🆘 Support

For support, please open an issue in the GitHub repository.

🔄 API Version

Current API version: ${API_VERSION:-"Not set"}

The API version is automatically set during the Docker build process based on the Git tag or commit hash. During CI/CD deployment (as defined in .forgejo/workflows/deploy-docker.yaml), the API_VERSION is determined using git describe --tags --always, which creates a version identifier based on the most recent Git tag and the number of commits since that tag. This version information is then embedded into the Docker image as a build argument and becomes accessible through the API_VERSION environment variable at runtime.