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

Initial commit: Extract base Zabbix GraphQl - API functionality from VCR Project and add dynamic schema samples

Browse source
This commit is contained in:
Andreas Hilbig 2026-01-05 21:05:35 +01:00
commit 92ffe71684
42 changed files with 4234 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

625
schema.graphql Normal file
View file

@ -0,0 +1,625 @@
# Scalars resolved by package "graphql-scalars"
scalar DateTime
scalar Time
scalar JSONObject
# Schema definitions go here
type Query {
"Get 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
"""
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
"""
allHosts(name_pattern: String = "", filter_host: String = null, hostids: Int,
groupids:[Int!] = null, with_items: Boolean = false, tag_deviceType:[String]=[], tag_hostType:[String!]): [Host]
"""
Get all host groups.
If with_hosts==true only groups with attached devices are delivered.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
"""
allHostGroups(search_name: String, 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
"""
locations(name_pattern: String = "", distinct_by_name: Boolean = true, templateids:[String] = null): [Location]
"""
Export device value history from Zabbix
Authentication: By zbx_session - cookie or zabbix-auth-token - header
"""
exportDeviceValueHistory(
"(Optional) list of deviceKeys to be included in the result"
deviceKey_filter: [String!],
"(Optional) list of attribute names to be included in the result"
attribute_filter: [String!],
"""
(Optional) timestamp of earliest deviceValue"""
time_from: DateTime,
"""(Optional) timestamp of last deviceValue """
time_until: DateTime,
"""Results are sorted by timestamps - ascending or descending order may be specified
using this parameter"""
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
"""
type: StorageItemType = FLOAT
):DeviceValueExportResponse
"""
Return all user permissions. If objectNames is provided return only the permissions related to the objects within
the objectNames - list
"""
userPermissions(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)
"""
hasPermissions(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
"""
exportUserRights(name_pattern: String = "" exclude_hostgroups_pattern: String = ""): UserRights
}
type UserRights {
userGroups: [UserGroup!]
userRoles: [UserRole!]
}
type UserRole {
roleid: Int!
name: String
type: Int
readonly: Int
rules: UserRoleRules
}
type UserRoleRules {
ui: [UserRoleRule!]
ui_default_access: Int
modules:[UserRoleModule!]
modules_default_access: Int
api_access: Int
api_mode: Int
api: [String!]
actions: [UserRoleRule!]
actions_default_access: Int
}
type UserRoleRule {
name: String
status: Int
}
type UserRoleModule {
moduleid: String
status: Int
id: String
relative_path: String
}
type UserGroup {
usrgrpid: Int!
name: String!
gui_access: Int
users_status: Int
hostgroup_rights: [ZabbixGroupRight!]
templategroup_rights: [ZabbixGroupRight!]
}
type ZabbixGroupRight {
id: Int!
uuid: String
name: String
permission: Permission
}
########################################################
# User permissions
########################################################
input PermissionRequest {
permission: Permission!,
"""
objectName maps to name / path suffix of the template group representing the permission in Zabbix:
Permissions/{objectName}
"""
objectName: String!
}
"""
READ, READ_WRITE or DENY:
describes the rights related to an objectName
There is no EXECUTE or anything else in Zabbix,
i.e. objectName - Tree has to be designed accordingly in order to represent the perform actions.
E.g.
Let's assume a button called "button1", used in application "app1", having a label which shows "do something". Instead of model the action "do something" the idea is
to model the effect of this action - do something will result in a status change. Let's further assume that the button will only
be displayed if the user is allowed to see the current status.
Permissions/app1/button1/status
The following PermissionRequests would be used by the frontend:
1. Should the button (and its status) be displayed at all?
button1.displayed = hasPermissions(
{
objectName: "app1/button1/status"
permission: READ
})
2. Should the user be able to press the button (enabled)?
button1.displayed = hasPermissions(
{
objectName: "app1/button1/status"
permission: READ_WRITE
})
Usage Example for this pattern: Activation/Deactivation of a control program - the button
shows the possible action. If the program is active it shows "Deactivate". If the program is inactive it shows "Activate".
From this label the user learns something about the current state - therefore the status - read - permission is needed in order
to display the button at all. The status write permission is needed in order to enable the button (i.e. allow the user to press it).
in order to model the permissions to press / see a button "button1" belonging to application "app1"
the following template group could be modelled in Zabbix
"""
enum Permission {
"""
DENY superseeds anything else - i.e. if in Zabbix there is a DENY and READ at the same time the result will be DENY
"""
DENY
"""
READ superseeds READ_WRITE - i.e. if in Zabbix there is a READ_WRITE and READ at the same time the resulting permission
level will be READ
"""
READ
"""
READ_WRITE implies the READ permission. Do not set both READ and READ_WRITE at the same time if you want to achieve
READ + WRITE permission, because in this case READ will superseed the READ_WRITE and the resulting permission level will be READ
"""
READ_WRITE
}
type UserPermission {
permission: Permission!,
"""
objectName maps to name / path suffix of the template group representing the permission in Zabbix:
Permissions/{objectName}
"""
objectName: String!
}
########################################################
# Device values
########################################################
enum StorageItemType {
FLOAT
INT
TEXT
}
type DeviceValueExportResponse {
result: [JSONObject!]
error: ApiError
}
############################################################################
type Mutation {
"""
Authentication: By zbx_session - cookie or zabbix-auth-token - header
"""
createHost(host: String!, hostgroupids:[Int!]!, templateids: [Int!]!,
location: LocationInput): ZabbixCreateResponse
"""
(Mass) Import zabbix 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
Authentication: By zbx_session - cookie or zabbix-auth-token - header
"""
importHostGroups(hostGroups: [CreateHostGroup!]!):[CreateHostGroupResponse!]
"""
(Mass) Import edge devices and assign them to host groups by groupid or groupName.
Return value: If no error occurs a hostid will be returned for each created device,
otherwise the return object will contain an error message. The hostid will be equal
to the provided deviceKey if the operation was successfull.
Authentication: By zbx_session - cookie or zabbix-auth-token - header
"""
importHosts(devices: [CreateHost!]!):[CreateHostResponse!]
importUserRights(input: UserRightsInput!, dryRun: Boolean! = true): ImportUserRightsResult
}
input UserRightsInput {
userRoles: [UserRoleInput!]
userGroups: [UserGroupInput!]
}
input UserRoleInput {
name: String
type: Int
readonly: Int
rules: UserRoleRulesInput
}
input UserRoleRulesInput {
ui: [UserRoleRuleInput!]
ui_default_access: Int
modules:[UserRoleModuleInput!]
modules_default_access: Int
api_access: Int
api_mode: Int
api: [String!]
actions: [UserRoleRuleInput!]
actions_default_access: Int
}
input UserRoleRuleInput {
name: String
status: Int
}
input UserRoleModuleInput {
moduleid: String
status: Int
id: String
}
input UserGroupInput {
name: String!
gui_access: Int
users_status: Int
hostgroup_rights: [ZabbixGroupRightInput!]
templategroup_rights: [ZabbixGroupRightInput!]
}
input ZabbixGroupRightInput {
uuid: String
"""
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
permission: Permission
}
type ImportUserRightsResult {
userRoles: [ImportUserRightResult!]
userGroups: [ImportUserRightResult!]
}
type ImportUserRightResult {
id: String
name: String
message: String
errors: [ApiError!]
}
"""
Hint: WGS84[dd.ddddd] coordinates are used
"""
interface GpsPosition {
latitude: Float
longitude: Float
}
#########################################
type HostGroup {
groupid: ID!
name: String
}
interface Host {
hostid: ID!
"""
The host field contains the "hostname" in Zabbix
"""
host: String!
deviceType: String
hostgroups: [HostGroup!]
name: String
tags: JSONObject
}
type ZabbixItem {
itemid: Int!
name: String!
key_: String!
hostid: Int
lastclock: Int
lastvalue: String
value_type: Int!
attributeName: String
deviceType: String
topicType:String
status: DeviceStatus
type: DeviceCommunicationType
hosts: [Host]
}
type ZabbixHost implements Host {
hostid: ID!
host: String!
deviceType: String
hostgroups: [HostGroup!]
name: String
tags: JSONObject
items: [ZabbixItem!]
inventory: Inventory
parentTemplates: [Template!]
}
"""
(IoT / Edge - ) Devices are hosts having a state containing the "output" / the business data which is exposed
besides monitoring information.
"""
interface Device implements Host {
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
"""
host: String!
deviceType: String
hostgroups: [HostGroup!]
name: String
tags: JSONObject
state: DeviceState
}
type OperationalDeviceData {
temperature: Float
voltage: Float
signalstrength: Float
location: Location
timestamp: DateTime
error: [ErrorPayload!]
}
interface DeviceState {
operational: OperationalDeviceData
}
# Generic IoT devices with "generic" current state - mapping all "values"
type GenericDeviceState implements DeviceState {
operational: OperationalDeviceData
current: JSONObject
}
"""
Device represents generic IoT / Edge - devices providing their state as generic "state.current" - JSON Object
"""
type GenericDevice implements Host & Device {
hostid: ID!
"""
Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
"""
host: String!
deviceType: String
hostgroups: [HostGroup!]
name: String
tags: JSONObject
state: GenericDeviceState
}
type ErrorPayload {
code: Int!
message: String
additionalInfo: JSONObject
}
enum SensorValueType {
NUMERIC # 0 - numeric float;
CHARACTER # 1 - character;
LOG # 2 - log;
NUMERIC_UNSIGNED # 3 - numeric unsigned;
TEXT # 4 - text;
}
type ZabbixCreateResponse {
hostids: [Int]
itemids: [Int]
error: ApiError
}
input LocationInput {
name: String
location_lat: String
location_lon: String
}
type Template {
templateid: String!
name: String
}
type Inventory {
location: Location
}
type Location implements GpsPosition {
name: String
latitude: Float
longitude: Float
}
enum DeviceStatus {
ENABLED
DISABLED
}
enum DeviceCommunicationType {
ZABBIX_AGENT
ZABBIX_AGENT_ACTIVE
ZABBIX_TRAP
ZABBIX_INTERNAL_ITEM
SIMPLE_CHECK
DEPENDANT_ITEM
SIMULATOR_CALCULATED
SIMULATOR_JAVASCRIPT
HTTP_AGENT
IPMI_AGENT
JMX_AGENT
SNMP_AGENT
SNMP_TRAP
DATABASE_MONITOR
}
type Item {
itemid: Int
hostid: Int
name: String!
key_: String
attributeName: String
deviceType: String
topicType:String
status: DeviceStatus
type: DeviceCommunicationType
hosts: [Host]
}
####################################################################
# Input types used for importXXX - and storeXXX - Mutations
####################################################################
input CreateHostGroup {
"""
Name of the host group
"""
groupName: String!
"""
Internally used unique id
(will be assigned by Zabbix if empty)
"""
uuid: String
}
type CreateHostGroupResponse {
groupName: String!
groupid: Int
message: String
error: ApiError
}
type HostTypeMeta {
deviceType: String
deviceTypeDescription: String
}
input CreateHost {
deviceKey: String!
"""
Optional display name of the device (must be unique if provided - default is to set display name to deviceKey)
"""
name: String
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
"""
groupNames: [String!]!
"""
Optionally the internal groupids can be passed - in this case the
groupName is ignored
"""
groupids: [Int]
location: LocationInput
}
type CreateHostResponse {
deviceKey: String!
hostid: String
message: String
error: ApiError
}
interface Error {
code: Int
message: String
data: JSONObject
}
type ApiError implements Error {
code: Int
message: String
data: JSONObject
path: String
args: JSONObject
}
############################################################################
# General purpose types + enums
############################################################################
enum SortOrder {
"Deliver values in ascending order"
asc
"Deliver values in descending order"
desc
}