zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity

docs: enhance GraphQL schema documentation

Browse source 
- Added comprehensive descriptions to all types, interfaces, and fields in 'schema/api_commons.graphql'.

- Improved documentation for mutations and input/response types in 'schema/mutations.graphql'.

- Added detailed descriptions for all queries and their arguments in 'schema/queries.graphql'.

- Enhanced documentation for core Zabbix types and enums in 'schema/zabbix.graphql'.

- Updated extension schemas under 'schema/extensions/' with proper GraphQL descriptions.

- Verified schema validity via 'graphql-codegen' and ran all tests to ensure consistency.
This commit is contained in:
Andreas Hilbig 2026-01-26 19:18:06 +01:00
parent 59815636ea
commit e61b5f4f11
11 changed files with 1330 additions and 344 deletions
Download patch file Download diff file Expand all files Collapse all files

51
schema/api_commons.graphql
View file

@ -2,22 +2,61 @@
# Request/response
########################################################
"""
Generic response wrapper containing either the result data or an error.
"""
type GenericResponse {
"""
The result data, typically a list of JSON objects.
"""
result: [JSONObject!]
"""
Error information if the operation failed.
"""
error: ApiError
}
"""
Detailed error information returned by the API.
"""
type ApiError implements Error {
"""
Error code.
"""
code: Int
"""
Error message.
"""
message: String
"""
Additional error data.
"""
data: JSONObject
"""
Path to the field that caused the error.
"""
path: String
"""
Arguments passed to the operation that failed.
"""
args: JSONObject
}
"""
Common error interface.
"""
interface Error {
"""
Error code.
"""
code: Int
"""
Error message.
"""
message: String
"""
Additional error data.
"""
data: JSONObject
}
@ -26,7 +65,13 @@ interface Error {
# User permissions
########################################################
"""
Request for checking specific user permissions.
"""
input PermissionRequest {
"""
The required permission level (DENY, READ, or READ_WRITE).
"""
permission: Permission!,
"""
objectName maps to name / path suffix of the template group representing the permission in Zabbix:
@ -89,7 +134,13 @@ enum Permission {
READ_WRITE
}
"""
Represents a permission assigned to a user for a specific object.
"""
type UserPermission {
"""
The assigned permission level.
"""
permission: Permission!,
"""
objectName maps to name / path suffix of the template group representing the permission in Zabbix:

3
schema/device_value_commons.graphql
View file

@ -45,5 +45,8 @@ interface DeviceValueMessage {
Marker-interface for device-related data values.
"""
interface DeviceValue {
"""
Dummy field to allow for empty interfaces.
"""
_empty: String
}

66
schema/devices.graphql
View file

@ -4,78 +4,136 @@
besides monitoring information.
"""
interface Device implements Host {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""State of the device."""
state: DeviceState
}
"""
Configuration settings for a device.
"""
type DeviceConfig {
"""
Configuration for the device widget preview in the cockpit.
"""
deviceWidgetPreview: WidgetPreview
}
"""
Represents the configuration for a 4-field widget preview.
"""
type WidgetPreview {
"""Top-left field specification."""
TOP_LEFT: DisplayFieldSpec
"""Top-right field specification."""
TOP_RIGHT: DisplayFieldSpec
"""Bottom-left field specification."""
BOTTOM_LEFT: DisplayFieldSpec
"""Bottom-right field specification."""
BOTTOM_RIGHT: DisplayFieldSpec
}
"""
Specification for a display field in a widget.
"""
type DisplayFieldSpec {
"""Key of the data to display."""
key: String,
"""Value to display if the data is missing."""
emptyValue: String
"""Unit string to append to the value."""
unit: String,
"""Font size for the value."""
value_font_size: String
"""Optional transformation for the value."""
g_value_transform: String
"""Font size for the unit."""
unit_font_size: String
"""Optional transformation for the unit."""
g_unit_transform: String
}
"""
Operational data common to most devices.
"""
type OperationalDeviceData {
"""Device temperature."""
temperature: Float
"""Device voltage."""
voltage: Float
"""Signal strength (e.g., WiFi or GSM)."""
signalstrength: Float
"""Current location of the device."""
location: Location
"""Timestamp of the operational data."""
timestamp: DateTime
"""List of active errors or status messages."""
error: [ErrorPayload!]
}
"""
Payload for a single error or status message.
"""
type ErrorPayload {
"""Error code."""
code: Int!
"""Human-readable error message."""
message: String
"""Additional contextual information about the error."""
additionalInfo: JSONObject
}
"""
Common interface for device state.
"""
interface DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
}
# Generic IoT devices with "generic" current state - mapping all "values"
"""
Generic implementation of device state using a JSON object for current values.
"""
type GenericDeviceState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current business data as a generic JSON object."""
current: JSONObject
}
"""
Device represents generic IoT / Edge - devices providing their state as generic "state.current" - JSON Object
Device represents generic IoT / Edge - devices providing their state as generic "state.current" - JSON Object.
"""
type GenericDevice implements Host & Device {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""State of the generic device."""
state: GenericDeviceState
}

44
schema/extensions/display_devices.graphql
View file

@ -16,60 +16,94 @@ type SinglePanelDevice implements Host & Device {
state: PanelState
}
"""
Represents the state of a single panel device.
"""
type PanelState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current display state."""
current: PanelCurrentState
}
"""
Represents the current state of a panel.
"""
type PanelCurrentState {
"""The current values being displayed on the panel."""
values: PanelValues
}
"""
Specific values displayed on a panel.
"""
type PanelValues {
"""
Index of the bitmap which is displayed
Index of the bitmap which is displayed.
"""
contentIndex: Int
"""
Hash of the bitmap which is displayed
Hash of the bitmap which is displayed.
"""
contentKey: String
"""
Text representation of what is displayed
Text representation of what is displayed.
"""
contentText: String
}
"""
The FourPanelDevice is a panel which allows to define pictures in 4
subpanels, called TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT
subpanels, called TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT.
"""
type FourPanelDevice implements Host & Device {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""State of the four-panel device."""
state: FourPanelState
}
"""
Represents the state of a four-panel device.
"""
type FourPanelState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current state of all four panels."""
current: FourPanelCurrentState
}
"""
Represents the combined current state of four panels.
"""
type FourPanelCurrentState {
"""The values for each of the four panels."""
values: FourPanelValues
}
"""
Values for each of the four panels in a FourPanelDevice.
"""
type FourPanelValues {
"""State of the top-left panel."""
TOP_LEFT: PanelValues
"""State of the top-right panel."""
TOP_RIGHT: PanelValues
"""State of the bottom-left panel."""
BOTTOM_LEFT: PanelValues
"""State of the bottom-right panel."""
BOTTOM_RIGHT: PanelValues
}

14
schema/extensions/location_tracker_commons.graphql
View file

@ -27,6 +27,9 @@ type SensorDistanceValue implements DeviceValue {
"""
time: String
"""
Dummy field to allow for empty interfaces.
"""
_empty: String
}
@ -34,8 +37,11 @@ type SensorDistanceValue implements DeviceValue {
Represents a coordinate in 3D space with x, y, and z components.
"""
type Position {
"""X coordinate."""
x: Float
"""Y coordinate."""
y: Float
"""Z coordinate."""
z: Float
}
@ -43,7 +49,9 @@ type Position {
Represents the result of a position calculation, including the calculated position and accuracy.
"""
type PositionCalculatorResult {
"""The calculated 3D position."""
position: Position
"""The estimated accuracy of the calculation."""
accuracy: Float
}
@ -51,10 +59,16 @@ type PositionCalculatorResult {
Concrete implementation of a DeviceValueMessage for sensor distance data.
"""
type SensorDistanceMessage implements DeviceValueMessage {
"""The unique identifier of the device."""
deviceKey: String
"""Timestamp of the message."""
timestamp: String
"""Name of the attribute."""
attributeName: String
"""Name of the topic."""
topicName: String
"""Type of the device."""
deviceType: String
"""The sensor distance value payload."""
value: SensorDistanceValue
}

24
schema/extensions/location_tracker_devices.graphql
View file

@ -1,45 +1,55 @@
"""
DistanceTracker represents a device which can detect other devices around itself and estimate
the distances, e.g. by using Bluetooth scanning technology and estimating the distance.
"""
type DistanceTrackerDevice implements Host & Device {
"""Internal Zabbix ID of the device."""
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
"""
host: String!
"""Classification of the device."""
deviceType: String
"""List of host groups this device belongs to."""
hostgroups: [HostGroup!]
"""Visible name of the device."""
name: String
"""Device configuration tags."""
tags: DeviceConfig
"""State of the distance tracker device."""
state: DistanceTrackerState
}
"""
Represents the state of a distance tracker device.
"""
type DistanceTrackerState implements DeviceState {
"""Operational data (telemetry)."""
operational: OperationalDeviceData
"""Current business values (detected devices and distances)."""
current: DistanceTrackerValues
}
"""
Aggregated information of devices detected around the tracker
Aggregated information of devices detected around the tracker.
"""
type DistanceTrackerValues {
"""
Start of time interval for the delivered device counting value
Start of time interval for the delivered device counting value.
"""
timeFrom: Time
"""
End of time interval for the delivered device counting value
End of time interval for the delivered device counting value.
"""
timeUntil: Time
"""
Number of unique deviceKeys detected between timeFrom and timeUnti
Number of unique device keys detected between timeFrom and timeUntil.
"""
count: Int
"""
Detailed information about devices detected nearby
Detailed information about devices detected nearby.
"""
distances: [SensorDistanceValue!]
}

506
schema/mutations.graphql
View file

@ -1,311 +1,647 @@
type Mutation {
"""
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Creates a single host in Zabbix.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
createHost(host: String!, hostgroupids:[Int!]!, templateids: [Int!]!,
location: LocationInput): CreateHostResponse
createHost(
"""Hostname of the new host."""
host: String!,
"""List of host group IDs to assign the host to."""
hostgroupids:[Int!]!,
"""List of template IDs to link to the host."""
templateids: [Int!]!,
"""Optional location information for the host inventory."""
location: LocationInput
): CreateHostResponse
"""
(Mass) Import zabbix groups
and assign them to the corresponding hosts by groupid or groupName.
(Mass) Import Zabbix host groups and assign them to the corresponding hosts by groupid or groupName.
Return value: If no error occurs a groupid be returned for each created group,
otherwise the return object will contain an error message
Return value: If no error occurs, a groupid is returned for each created group; otherwise, the return object contains an error message.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
importHostGroups(hostGroups: [CreateHostGroup!]!):[CreateHostGroupResponse!]
importHostGroups(
"""List of host groups to import."""
hostGroups: [CreateHostGroup!]!
):[CreateHostGroupResponse!]
"""
(Mass) Import hosts and assign them to host groups by groupid or groupName.
Return value: If no error occurs a hostid will be returned for each created host,
otherwise the return object will contain an error message.
Return value: If no error occurs, a hostid is returned for each created host; otherwise, the return object contains an error message.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
importHosts(hosts: [CreateHost!]!):[ImportHostResponse!]
importUserRights(input: UserRightsInput!, dryRun: Boolean! = true): ImportUserRightsResult
importHosts(
"""List of hosts to import."""
hosts: [CreateHost!]!
):[ImportHostResponse!]
"""
(Mass) Import template groups
and assign them by groupid or name.
Return value: If no error occurs a groupid be returned for each created group,
otherwise the return object will contain an error message
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Import user rights (roles and groups) into Zabbix.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
importTemplateGroups(templateGroups: [CreateTemplateGroup!]!):[CreateTemplateGroupResponse!]
importUserRights(
"""User rights configuration to import."""
input: UserRightsInput!,
"""If true, only validates the input without applying changes."""
dryRun: Boolean! = true
): ImportUserRightsResult
"""
(Mass) Import template groups and assign them by groupid or name.
Return value: If no error occurs, a groupid is returned for each created group; otherwise, the return object contains an error message.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
importTemplateGroups(
"""List of template groups to import."""
templateGroups: [CreateTemplateGroup!]!
):[CreateTemplateGroupResponse!]
"""
(Mass) Import templates.
Return value: If no error occurs a templateid will be returned for each created template,
otherwise the return object will contain an error message.
Return value: If no error occurs, a templateid is returned for each created template; otherwise, the return object contains an error message.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
importTemplates(templates: [CreateTemplate!]!):[ImportTemplateResponse!]
importTemplates(
"""List of templates to import."""
templates: [CreateTemplate!]!
):[ImportTemplateResponse!]
"""
Delete templates.
Delete templates by their IDs or by a name pattern.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
deleteTemplates(templateids: [Int!], name_pattern: String): [DeleteResponse!]
deleteTemplates(
"""List of template IDs to delete."""
templateids: [Int!],
"""Wildcard name pattern for templates to delete (e.g., 'Template%')."""
name_pattern: String
): [DeleteResponse!]
"""
Delete template groups.
Delete template groups by their IDs or by a name pattern.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
deleteTemplateGroups(groupids: [Int!], name_pattern: String): [DeleteResponse!]
deleteTemplateGroups(
"""List of template group IDs to delete."""
groupids: [Int!],
"""Wildcard name pattern for template groups to delete."""
name_pattern: String
): [DeleteResponse!]
}
####################################################################
# Input types used for importXXX - and storeXXX - Mutations
####################################################################
"""
Response object for delete operations.
"""
type DeleteResponse {
"""
ID of the deleted entity.
"""
id: Int!
"""
Status message for the delete operation.
"""
message: String
"""
Error information if the deletion failed.
"""
error: ApiError
}
"""
Input for creating or identifying a template group.
"""
input CreateTemplateGroup {
"""
Name of the template group
Name of the template group.
"""
groupName: String!
"""
Internally used unique id
(will be assigned by Zabbix if empty)
Internally used unique id (will be assigned by Zabbix if empty).
"""
uuid: String
}
"""
Input for creating or updating a template.
"""
input CreateTemplate {
"""
Name of the template
Technical name of the template.
"""
host: String!
"""
Visible name of the template
Visible name of the template.
"""
name: String
"""
groupNames is used to assign the created object
to a template group.
List of template group names to assign the template to.
"""
groupNames: [String!]!
"""
Optionally the internal groupids can be passed - in this case the
groupName is ignored
Optionally, internal group IDs can be provided instead of group names.
"""
groupids: [Int]
"""
Internally used unique id
(will be assigned by Zabbix if empty)
Internally used unique id (will be assigned by Zabbix if empty).
"""
uuid: String
"""
Template items
List of items to create within the template.
"""
items: [CreateTemplateItem!]
"""
Linked templates
List of other templates to link to this template.
"""
templates: [CreateLinkedTemplate!]
"""
Template tags
Tags to assign to the template.
"""
tags: [CreateTag!]
}
"""
Input for creating an item within a template.
"""
input CreateTemplateItem {
"""
Internally used unique id.
"""
uuid: String
"""
Name of the item.
"""
name: String!
"""
Zabbix item type (e.g., 0 for Zabbix Agent, 18 for Dependent).
"""
type: Int
"""
Technical key of the item.
"""
key: String!
"""
Type of information (e.g., 0 for Float, 3 for Int, 4 for Text).
"""
value_type: Int
"""
History storage period (e.g., '2d', '90d').
"""
history: String
"""
Units of the value.
"""
units: String
"""
Update interval.
"""
delay: String
"""
Description of the item.
"""
description: String
"""
Preprocessing steps for the item values.
"""
preprocessing: [CreateItemPreprocessing!]
"""
Tags to assign to the item.
"""
tags: [CreateTag!]
"""
Reference to a master item if this is a dependent item.
"""
master_item: CreateMasterItem
}
"""
Reference to a master item for dependent items.
"""
input CreateMasterItem {
"""
The technical key of the master item.
"""
key: String!
}
"""
Input for an item preprocessing step.
"""
input CreateItemPreprocessing {
"""
Type of preprocessing step (e.g., 12 for JSONPath, 21 for JavaScript).
"""
type: Int!
"""
Parameters for the preprocessing step.
"""
params: [String!]!
"""
Error handling behavior.
"""
error_handler: Int
"""
Error handling parameters.
"""
error_handler_params: String
}
"""
Reference to a template to be linked.
"""
input CreateLinkedTemplate {
"""
The technical name of the template to link.
"""
name: String!
}
"""
Input for a tag.
"""
input CreateTag {
"""
Tag name.
"""
tag: String!
"""
Tag value.
"""
value: String
}
"""
Response for a template import operation.
"""
type ImportTemplateResponse {
"""
The technical name of the imported template.
"""
host: String!
"""
The Zabbix template ID assigned to the template.
"""
templateid: String
"""
Status message for the import.
"""
message: String
"""
Error information if the import failed.
"""
error: ApiError
}
"""
Response for a template group import operation.
"""
type CreateTemplateGroupResponse {
"""
Name of the imported template group.
"""
groupName: String!
"""
The Zabbix group ID assigned to the group.
"""
groupid: Int
"""
Status message for the import.
"""
message: String
"""
Error information if the import failed.
"""
error: ApiError
}
"""
Input for creating or identifying a host group.
"""
input CreateHostGroup {
"""
Name of the host group
Name of the host group.
"""
groupName: String!
"""
Internally used unique id
(will be assigned by Zabbix if empty)
Internally used unique id (will be assigned by Zabbix if empty).
"""
uuid: String
}
"""
Response for a host import operation.
"""
type ImportHostResponse {
deviceKey: String!
hostid: String
message: String
error: ApiError
}
type CreateHostGroupResponse {
groupName: String!
groupid: Int
message: String
error: ApiError
}
input CreateHost {
"""
The device key (technical name) of the imported host.
"""
deviceKey: String!
"""
Optional display name of the device (must be unique if provided - default is to set display name to deviceKey)
The Zabbix host ID assigned to the host.
"""
hostid: String
"""
Status message for the import.
"""
message: String
"""
Error information if the import failed.
"""
error: ApiError
}
"""
Response for a host group import operation.
"""
type CreateHostGroupResponse {
"""
Name of the imported host group.
"""
groupName: String!
"""
The Zabbix group ID assigned to the group.
"""
groupid: Int
"""
Status message for the import.
"""
message: String
"""
Error information if the import failed.
"""
error: ApiError
}
"""
Input for creating a new host.
"""
input CreateHost {
"""
Technical name of the host/device.
"""
deviceKey: String!
"""
Optional display name of the device (must be unique if provided - default is to set display name to deviceKey).
"""
name: String
"""
Classification or category of the device.
"""
deviceType: String!
"""
groupNames is used to assign the created object
to a host group. It is mandatory but
can also be blank. This is usefull in case of
passing a groupid instead which is
the zabbix internal key for storing the group.
If a groupid is provided the passed groupName is ignored
List of host group names to assign the host to.
"""
groupNames: [String!]!
"""
Optionally the internal groupids can be passed - in this case the
groupName is ignored
Optionally, internal group IDs can be provided instead of group names.
"""
groupids: [Int]
"""
Location information for the host.
"""
location: LocationInput
}
"""
Response for a single host creation operation.
"""
type CreateHostResponse {
"""
List of created host IDs.
"""
hostids: [Int]
"""
List of created item IDs.
"""
itemids: [Int]
"""
Error information if the creation failed.
"""
error: ApiError
}
"""
Input for host location information.
"""
input LocationInput {
"""
Name of the location.
"""
name: String
"""
Latitude coordinate.
"""
location_lat: String
"""
Longitude coordinate.
"""
location_lon: String
}
#######################################
# Permission related input
#######################################
"""
Input for importing user rights.
"""
input UserRightsInput {
"""
List of user roles to import.
"""
userRoles: [UserRoleInput!]
"""
List of user groups to import.
"""
userGroups: [UserGroupInput!]
}
"""
Input for a user role.
"""
input UserRoleInput {
"""
Name of the role.
"""
name: String
"""
Type of role (e.g., 1 for User, 2 for Admin, 3 for Super Admin).
"""
type: Int
"""
Whether the role is read-only (1) or not (0).
"""
readonly: Int
"""
Specific rules for the role.
"""
rules: UserRoleRulesInput
}
"""
Input for user role rules.
"""
input UserRoleRulesInput {
"""
UI access rules.
"""
ui: [UserRoleRuleInput!]
"""
Default access for UI elements.
"""
ui_default_access: Int
"""
Module access rules.
"""
modules:[UserRoleModuleInput!]
"""
Default access for modules.
"""
modules_default_access: Int
"""
Whether API access is enabled (1) or not (0).
"""
api_access: Int
"""
API mode (e.g., 0 for white-list, 1 for black-list).
"""
api_mode: Int
"""
List of API methods allowed/denied.
"""
api: [String!]
"""
Action rules.
"""
actions: [UserRoleRuleInput!]
"""
Default access for actions.
"""
actions_default_access: Int
}
"""
Input for a single user role rule.
"""
input UserRoleRuleInput {
"""
Name of the rule/element.
"""
name: String
"""
Status (e.g., 1 for enabled, 0 for disabled).
"""
status: Int
}
"""
Input for user role module access.
"""
input UserRoleModuleInput {
"""
The internal Zabbix module ID.
"""
moduleid: String
"""
Status of the module.
"""
status: Int
"""
Technical ID of the module.
"""
id: String
}
"""
Input for a user group.
"""
input UserGroupInput {
"""
Name of the user group.
"""
name: String!
"""
Frontend access level.
"""
gui_access: Int
"""
Status of the users in the group.
"""
users_status: Int
"""
Permissions for host groups.
"""
hostgroup_rights: [ZabbixGroupRightInput!]
"""
Permissions for template groups.
"""
templategroup_rights: [ZabbixGroupRightInput!]
}
"""
Input for a Zabbix group permission right.
"""
input ZabbixGroupRightInput {
"""
The unique ID of the group.
"""
uuid: String
"""
name may optionally be specified for documentation purpose,
Name may optionally be specified for documentation purpose,
but the master for setting the user right is the uuid.
If a uuid is found and the corresponding group
has a deviating name this will be documented within a message
with errorcode = 0 (OK) but the permission will be set (
the reason is that names for groups may deviate between several
instances of the control center although the semantic is the same -
while the semantic is identified by uuid.
"""
name: String
"""
The permission level to assign.
"""
permission: Permission
}
"""
Result of a user rights import operation.
"""
type ImportUserRightsResult {
"""
Results for the imported user roles.
"""
userRoles: [ImportUserRightResult!]
"""
Results for the imported user groups.
"""
userGroups: [ImportUserRightResult!]
}
"""
Result of a single user right (role or group) import.
"""
type ImportUserRightResult {
"""
The ID of the imported/updated entity.
"""
id: String
"""
The name of the entity.
"""
name: String
"""
Status message for the import.
"""
message: String
"""
List of errors encountered during import.
"""
errors: [ApiError!]
}

196
schema/queries.graphql
View file

@ -4,124 +4,170 @@ scalar Time
scalar JSONObject
type Query {
"Get api (build) version"
"""
Returns the API build version.
"""
apiVersion: String!
"Get zabbix version"
zabbixVersion: String
"""
Login to zabbix - provided for debugging and testing purpose. The result of the login operation is
authentication token returned may be passed as
header 'zabbix-auth-token' for authenticating future API requests.
As an alternative to the cookie 'zbx_session' may be set which is automatically set after login to
the cockpit - this is the standard way to authenticate api calls initiated by the cockpit frontend
because the frontend is always embedded into the Zabbix portal which is only accessible after logging in and
obtainind the zbx_session - cookie.
"""
login(username: String!, password: String!): String
"""
Logout from zabbix - provided for debugging and testing purpose. This invalidates the token received by the login
operation. Returns true on success
Returns the version of the connected Zabbix instance.
"""
zabbixVersion: String
"""
Logs in to Zabbix. This is primarily for debugging and testing.
The returned authentication token can be passed in the `zabbix-auth-token` header for future requests.
Alternatively, the `zbx_session` cookie can be used for authentication.
"""
login(
"""Zabbix username."""
username: String!,
"""Zabbix password."""
password: String!
): String
"""
Logs out from Zabbix, invalidating the current session/token.
"""
logout: Boolean
"""
Get all hosts + corresponding items. If with_items==true only hosts with attached items are delivered
name_pattern: If provided this will perform a LIKE "%…%" search on the name attribute within the database.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Returns all hosts and their items.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
allHosts(name_pattern: String = "", filter_host: String = null, hostids: Int,
groupids:[Int!] = null, with_items: Boolean = false, tag_deviceType:[String]=[], tag_hostType:[String!]): [Host]
allHosts(
"""Wildcard name pattern for filtering hosts (LIKE '%...%')."""
name_pattern: String = "",
"""Filter hosts by their technical name."""
filter_host: String = null,
"""Filter by a specific host ID."""
hostids: Int,
"""Filter by host group IDs."""
groupids:[Int!] = null,
"""If true, only returns hosts that have items attached."""
with_items: Boolean = false,
"""Filter by `deviceType` tag."""
tag_deviceType:[String]=[],
"""Filter by `hostType` tag."""
tag_hostType:[String!]
): [Host]
"""
Get all devices + corresponding items. Devices are modelled as hosts having a device type + a state.
If with_items==true only hosts with attached items are delivered
name_pattern: If provided this will perform a LIKE "%…%" search on the name attribute within the database.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Returns all devices and their items. Devices are hosts with a `deviceType` and a state.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
allDevices(name_pattern: String = "", filter_host: String = null, hostids: Int,
groupids:[Int!] = null, with_items: Boolean = false, tag_deviceType:[String]=[], tag_hostType:[String!]): [Device]
allDevices(
"""Wildcard name pattern for filtering devices (LIKE '%...%')."""
name_pattern: String = "",
"""Filter devices by their technical name."""
filter_host: String = null,
"""Filter by a specific host ID."""
hostids: Int,
"""Filter by host group IDs."""
groupids:[Int!] = null,
"""If true, only returns devices that have items attached."""
with_items: Boolean = false,
"""Filter by `deviceType` tag."""
tag_deviceType:[String]=[],
"""Filter by `hostType` tag."""
tag_hostType:[String!]
): [Device]
"""
Get all host groups.
If with_hosts==true only groups with attached hosts are delivered.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Returns all host groups.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
allHostGroups(search_name: String, with_hosts: Boolean = true): [HostGroup]
allHostGroups(
"""Search for host groups by name (supports wildcards)."""
search_name: String,
"""If true, only returns groups that have hosts attached."""
with_hosts: Boolean = true
): [HostGroup]
"""
Get all locations used by hosts.
distinct_by_name=true means that the result is filtered for distinct names (default)
name_pattern: If provided this will perform a Regex search on the name attribute within the database.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Returns all locations used by hosts.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
locations(name_pattern: String = "", distinct_by_name: Boolean = true, templateids:[String] = null): [Location]
locations(
"""Regex name pattern for filtering locations."""
name_pattern: String = "",
"""If true, filters the result for distinct names."""
distinct_by_name: Boolean = true,
"""Filter by template IDs used by the hosts."""
templateids:[String] = null
): [Location]
"""
Export history from Zabbix items
Authentication: By zbx_session - cookie or zabbix-auth-token - header
Exports value history for Zabbix items.
Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
"""
exportHostValueHistory(
"(Optional) list of hostnames to be included in the result"
"""Optional list of hostnames to be included in the result."""
host_filter: [String!],
"(Optional) list of item keys to be included in the result"
"""Optional list of item keys to be included in the result."""
itemKey_filter: [String!],
"""
(Optional) timestamp of earliest value"""
"""Timestamp of the earliest value to include."""
time_from: DateTime,
"""(Optional) timestamp of last value """
"""Timestamp of the last value to include."""
time_until: DateTime,
"""Results are sorted by timestamps - ascending or descending order may be specified
using this parameter"""
"""Sort order for the results (asc or desc)."""
sortOrder: SortOrder=desc,
"""
Maximum number of records to be delivered. Hint: This might be useful, because the
current version of Zabbix delivers a 500 - error in case of requesting too much data
"""
limit: Int
"""
As values are stored in different data structures depending on their type
the type information must be specified in advance, although
each value (also if number) is converted into a string afterwards
"""
"""Maximum number of records to return."""
limit: Int,
"""The data type of the values being retrieved."""
type: StorageItemType = FLOAT
):GenericResponse
): GenericResponse
"""
Return all user permissions. If objectNames is provided return only the permissions related to the objects within
the objectNames - list
Returns all user permissions.
If `objectNames` is provided, returns only the permissions related to those objects.
"""
userPermissions(objectNames: [String!]): [UserPermission!]
userPermissions(
"""Optional list of object names to filter by."""
objectNames: [String!]
): [UserPermission!]
"""
Return true if and only if the current user (identified by token / cookie)
has all requested permissions (minimum - if READ is requested and the user has READ_WRITE
the response will be true)
Checks if the current user has the requested permissions.
"""
hasPermissions(permissions: [PermissionRequest!]!): Boolean
hasPermissions(
"""List of permissions to check."""
permissions: [PermissionRequest!]!
): Boolean
"""
name_pattern: If provided this will perform a LIKE "%…%" search on the name attribute within the database.
exclude_groups_pattern: Regex allowing to exclude all matching hostgroups from group permissions
Exports user rights (roles and groups).
"""
exportUserRights(name_pattern: String = "" exclude_hostgroups_pattern: String = ""): UserRights
exportUserRights(
"""Wildcard name pattern for filtering (LIKE '%...%')."""
name_pattern: String = ""
"""Regex to exclude matching host groups from group permissions."""
exclude_hostgroups_pattern: String = ""
): UserRights
"""
Get templates.
Returns templates.
"""
templates(hostids: [Int], name_pattern: String): [Template]
templates(
"""Filter by specific template IDs."""
hostids: [Int],
"""Wildcard name pattern for filtering templates."""
name_pattern: String
): [Template]
"""
Get template groups.
Returns all template groups.
"""
allTemplateGroups(name_pattern: String): [HostGroup]
allTemplateGroups(
"""Wildcard name pattern for filtering template groups."""
name_pattern: String
): [HostGroup]
}

217
schema/zabbix.graphql
View file

@ -2,18 +2,39 @@
# Hosts, items + groups, templates
###################################
"""
Represents a host group in Zabbix.
"""
type HostGroup {
"""
Internal Zabbix ID of the host group.
"""
groupid: ID!
"""
Name of the host group.
"""
name: String
}
"""
Common interface for all host-like entities in Zabbix.
"""
interface Host {
"""
Internal Zabbix ID of the host.
"""
hostid: ID!
"""
The host field contains the "hostname" in Zabbix
Technical name of the host (the 'hostname' in Zabbix).
"""
host: String!
"""
List of host groups this host belongs to.
"""
hostgroups: [HostGroup!]
"""
Visible name of the host.
"""
name: String
"""
Specifies the type or category of the device. Used to define the classification
@ -22,42 +43,113 @@ interface Host {
deviceType: String
}
"""
Represents a Zabbix item (a single data point being monitored).
"""
type ZabbixItem {
"""
Internal Zabbix ID of the item.
"""
itemid: Int!
"""
Visible name of the item.
"""
name: String!
"""
Technical key of the item.
"""
key_: String!
"""
Internal Zabbix ID of the host this item belongs to.
"""
hostid: Int
"""
Unix timestamp of the last time the item value was updated.
"""
lastclock: Int
"""
Last value retrieved for this item.
"""
lastvalue: String
"""
Type of information (e.g., 0 for Float, 3 for Int, 4 for Text).
"""
value_type: Int!
"""
Attribute name if this item is part of a hierarchical mapping.
"""
attributeName: String
"""
Status of the item (ENABLED or DISABLED).
"""
status: DeviceStatus
"""
Communication type used by the item.
"""
type: DeviceCommunicationType
"""
Hosts that this item is linked to.
"""
hosts: [Host!]
}
"""
Enum representing the different communication methods Zabbix uses to collect data.
"""
enum DeviceCommunicationType {
"""Zabbix agent."""
ZABBIX_AGENT
"""Zabbix agent (active)."""
ZABBIX_AGENT_ACTIVE
"""Zabbix trapper."""
ZABBIX_TRAP
"""Zabbix internal."""
ZABBIX_INTERNAL_ITEM
"""Simple check."""
SIMPLE_CHECK
"""Dependent item."""
DEPENDANT_ITEM
"""Calculated item."""
SIMULATOR_CALCULATED
"""JavaScript item."""
SIMULATOR_JAVASCRIPT
"""HTTP agent."""
HTTP_AGENT
"""IPMI agent."""
IPMI_AGENT
"""JMX agent."""
JMX_AGENT
"""SNMP agent."""
SNMP_AGENT
"""SNMP trap."""
SNMP_TRAP
"""Database monitor."""
DATABASE_MONITOR
}
"""
Concrete implementation of a Zabbix host.
"""
type ZabbixHost implements Host {
"""
Internal Zabbix ID of the host.
"""
hostid: ID!
"""
Technical name of the host.
"""
host: String!
"""
List of host groups this host belongs to.
"""
hostgroups: [HostGroup!]
"""
Visible name of the host.
"""
name: String
"""
Tags assigned to the host as a JSON object.
"""
tags: JSONObject
"""
@ -66,36 +158,85 @@ type ZabbixHost implements Host {
"""
deviceType: String
"""
List of monitored items for this host.
"""
items: [ZabbixItem!]
"""
Host inventory data.
"""
inventory: Inventory
"""
List of templates linked to this host.
"""
parentTemplates: [Template!]
}
"""
Represents a Zabbix template.
"""
type Template {
"""
Internal Zabbix ID of the template.
"""
templateid: String!
"""
Name of the template.
"""
name: String
}
"""
Represents host inventory information.
"""
type Inventory {
"""
Location data for the host.
"""
location: Location
}
"""
Hint: WGS84[dd.ddddd] coordinates are used
Interface for entities that have GPS coordinates.
Hint: WGS84[dd.ddddd] coordinates are used.
"""
interface GpsPosition {
"""
Latitude coordinate.
"""
latitude: Float
longitude: Float
}
type Location implements GpsPosition {
name: String
latitude: Float
"""
Longitude coordinate.
"""
longitude: Float
}
"""
Represents a geographical location.
"""
type Location implements GpsPosition {
"""
Name of the location.
"""
name: String
"""
Latitude coordinate.
"""
latitude: Float
"""
Longitude coordinate.
"""
longitude: Float
}
"""
Status of a Zabbix device/item.
"""
enum DeviceStatus {
"""The device/item is enabled."""
ENABLED
"""The device/item is disabled."""
DISABLED
}
@ -103,62 +244,124 @@ enum DeviceStatus {
# History / Values
########################################################
"""
Enum representing the storage data types for monitored items.
"""
enum StorageItemType {
"""Floating point number."""
FLOAT
"""Unsigned integer."""
INT
"""Textual data."""
TEXT
}
############################
# Permissions
############################
"""
Represents the combined user rights (groups and roles).
"""
type UserRights {
"""List of user groups."""
userGroups: [UserGroup!]
"""List of user roles."""
userRoles: [UserRole!]
}
"""
Represents a Zabbix user role.
"""
type UserRole {
"""Internal Zabbix ID of the role."""
roleid: Int!
"""Name of the role."""
name: String
"""Type of the role."""
type: Int
"""Whether the role is read-only."""
readonly: Int
"""Rules assigned to the role."""
rules: UserRoleRules
}
"""
Represents the rules assigned to a user role.
"""
type UserRoleRules {
"""UI access rules."""
ui: [UserRoleRule!]
"""Default access for UI elements."""
ui_default_access: Int
"""Module access rules."""
modules:[UserRoleModule!]
"""Default access for modules."""
modules_default_access: Int
"""Whether API access is enabled."""
api_access: Int
"""API mode."""
api_mode: Int
"""List of API methods allowed/denied."""
api: [String!]
"""Action rules."""
actions: [UserRoleRule!]
"""Default access for actions."""
actions_default_access: Int
}
"""
Represents a single rule within a user role.
"""
type UserRoleRule {
"""Name of the rule."""
name: String
"""Status of the rule."""
status: Int
}
"""
Represents a module assigned to a user role.
"""
type UserRoleModule {
"""Internal Zabbix module ID."""
moduleid: String
"""Status of the module."""
status: Int
"""Technical ID of the module."""
id: String
"""Relative path to the module."""
relative_path: String
}
"""
Represents a Zabbix user group.
"""
type UserGroup {
"""Internal Zabbix ID of the user group."""
usrgrpid: Int!
"""Name of the user group."""
name: String!
"""Frontend access level."""
gui_access: Int
"""Status of users in the group."""
users_status: Int
"""Permissions for host groups."""
hostgroup_rights: [ZabbixGroupRight!]
"""Permissions for template groups."""
templategroup_rights: [ZabbixGroupRight!]
}
"""
Represents a specific permission right for a group.
"""
type ZabbixGroupRight {
"""ID of the group the right applies to."""
id: Int!
"""Unique ID of the group."""
uuid: String
"""Name of the group."""
name: String
"""Assigned permission level."""
permission: Permission
}