zabbix-graphql-api/README.md

Zabbix GraphQL API

A modern GraphQL interface for Zabbix, providing enhanced features and easier integration for automation and management.

Purpose

The Zabbix GraphQL API acts as a wrapper and enhancer for the native Zabbix JSON-RPC API. It simplifies complex operations, provides a strongly-typed schema, and adds advanced logic for importing, querying, and managing Zabbix entities like hosts, templates, and user rights.

Key Features & Enhancements

Compared to the original Zabbix API, this GraphQL API provides several key enhancements:

• Mass Import/Export: Robust support for importing and exporting templates, template groups, hosts, and host groups in bulk.
• Hierarchical Host Groups: Automatically handles the creation and resolution of nested host group hierarchies (e.g., Parent/Child/Leaf).
• Template Management:
  • Full support for template items, including complex preprocessing steps and tags.
  • Dependent Item Support: Intelligent deferred creation logic to handle item dependencies within a template.
  • Linked template resolution by name.
• Advanced Deletion: Ability to delete templates and template groups not only by ID but also by name patterns (supporting Zabbix wildcards like %).
• User Rights & Permissions:
  • Integrated management of user roles and user groups.
  • Support for importing/exporting user rights with UUID-based matching for cross-instance consistency.
  • On-the-fly permission checks (hasPermissions, userPermissions).
• Improved Error Reporting: Detailed error data from Zabbix is appended to GraphQL error messages, making debugging significantly easier.
• Strongly Typed Schema: Leverages GraphQL's type system for clear API documentation and client-side code generation.

How to Install and Start

Prerequisites

• Node.js: Version 18 or higher recommended.
• Zabbix: A running Zabbix instance (compatible with Zabbix 6.0+).

Installation

1. Clone the repository:

   git clone <repository-url>
   cd zabbix-graphql-api
   

2. Install dependencies:

   npm install
   

Configuration

The API is configured via environment variables. Create a .env file or set them in your environment:

Variable	Description	Default
ZABBIX_BASE_URL	URL to your Zabbix API (e.g., http://zabbix.example.com/zabbix)
ZABBIX_AUTH_TOKEN	Zabbix Super Admin API token for administrative tasks
ZABBIX_EDGE_DEVICE_BASE_GROUP	Base host group for devices	Baustellen-Devices
SCHEMA_PATH	Path to the directory containing .graphql schema files	./schema/

Starting the API

Development Mode

Starts the server with nodemon and tsx for automatic reloading:

npm run start

Production Mode

Builds the project and runs the compiled code:

npm run prod

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

Usage Samples

The docs directory contains several sample GraphQL queries and mutations to help you get started:

• Hosts:
  • Query All Hosts
  • Import Hosts
• Templates:
  • Query Templates
  • Import Templates
  • Delete Templates
• Template Groups:
  • Import Template Groups
  • Delete Template Groups
• User Rights:
  • Export User Rights
  • Import User Rights

License

This project is licensed under the GNU Affero General Public License v3.0. See the LICENSE file for details.