docs: add README.md and LICENSE file

- Created README.md with project purpose, features, installation guide, and usage samples. - Added LICENSE file with GNU General Public License v2.0 to match Zabbix license.
2026-01-26 17:06:20 +01:00 · 2026-01-26 17:06:20 +01:00 · 825cb4d918
commit 825cb4d918
parent fdfd5f1e0e
2 changed files with 374 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,94 @@
+# 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:
+    ```bash
+    git clone <repository-url>
+    cd zabbix-graphql-api
+    ```
+
+2.  Install dependencies:
+    ```bash
+    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:
+```bash
+npm run start
+```
+
+#### Production Mode
+Builds the project and runs the compiled code:
+```bash
+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](docs/sample_all_hosts_query.graphql)
+    *   [Import Hosts](docs/sample_import_hosts_mutation.graphql)
+*   **Templates**:
+    *   [Query Templates](docs/sample_templates_query.graphql)
+    *   [Import Templates](docs/sample_import_templates_mutation.graphql)
+    *   [Delete Templates](docs/sample_delete_templates_mutation.graphql)
+*   **Template Groups**:
+    *   [Import Template Groups](docs/sample_import_template_groups_mutation.graphql)
+    *   [Delete Template Groups](docs/sample_delete_template_groups_mutation.graphql)
+*   **User Rights**:
+    *   [Export User Rights](docs/sample_export_user_rights_query.graphql)
+    *   [Import User Rights](docs/sample_import_user_rights_mutation.graphql)
+
+## License
+
+This project is licensed under the **GNU General Public License v2.0**, the same license agreement as the original Zabbix source. See the [LICENSE](LICENSE) file for details.