Centralised Config API

Note

Version: 2.2.0
Base URL: https://next.itrslab.com/rest/centralised-config/v1/

The Centralised Gateway Configuration API provides a publicly accessible REST API for managing gateway configurations in Obcerv. This API allows you to create, retrieve, update, and delete gateway configurations and their associated resources.

Authentication Copied

All endpoints require Bearer token authentication using the Authorization: Bearer <token> header.

Artifacts Management Copied

Get Gateway Artifacts Copied

GET /artifacts/gateways

Lists all stored gateway archive versions.

Example Response:

{
  "versions": ["GA5.7.1-230112", "GA6.1.0-230204"]
}

Delete Gateway Artifact Copied

DELETE /artifacts/gateways

Removes a stored gateway archive. This operation can only be performed by administrators.

Example Request:

DELETE /artifacts/gateways?version=GA6.2.0-230101

Gateway Management Copied

Get Gateways Copied

GET /configuration/gateways

Returns a list of gateways filtered by a regular expression pattern applied to the gateway’s name. Only the latest version of each gateway is returned.

Example Request:

GET /configuration/gateways?pattern=.*&limit=100&skip=0

Example Response:

[
  {
    "id": 1,
    "name": "EMEA/Infrastructure",
    "version": "GA4.7.1",
    "setupValidationId": 3
  }
]

Create Gateway Copied

POST /configuration/gateways

Creates a named gateway and associates it with a single resource. The resource will be automatically created and named Gateway/<Gateway_Name>.

Request Body:

{
  "name": "Gateway/EMEA",
  "version": "GA4.5.1-220111"
}

Example Response:

{
  "id": 10
}

Get Gateway Details Copied

GET /configuration/gateways/{gatewayId}

Gets a list of resources used by a specific gateway and metadata about the gateway itself.

Example Response:

{
  "id": 1,
  "name": "EMEA/Infrastructure",
  "version": "GA4.7.1",
  "resources": [
    {
      "id": 1,
      "name": "Samplers/Infrastructure",
      "version": "2",
      "hash": "f0ef7bbda8e1812f72bd2f2571d4bebe",
      "mainResource": false
    }
  ],
  "setupValidationId": 3
}

Delete Gateway Copied

DELETE /configuration/gateways/{gatewayId}

Deletes an existing gateway and its main resource. This operation can only be performed by administrators and is irreversible.

Get Gateway History Copied

GET /configuration/gateways/{gatewayId}/archives

Returns an ordered list of historic versions of a gateway matching the supplied ID.

Update Gateway Version Copied

PUT /configuration/gateways/{gatewayId}/version

Updates the geneos version of a gateway.

Request Body:

{
  "version": "GA4.5.1-221010"
}

Resource Management Copied

Get Resources Copied

GET /configuration/gateways/resources

Returns a list of resources filtered by a regular expression pattern applied to the resource’s name. Only the latest version of each resource is returned.

Example Request:

GET /configuration/gateways/resources?pattern=^Sampler.*&limit=100&skip=0

Create Resource Copied

POST /configuration/gateways/resources

Creates a new named resource with the contents provided. A resource is an XML document that can be used as part of the setup of a Gateway.

Content-Type: multipart/form-data

Form Fields:

• resource: JSON metadata for the resource
• contents: XML content or gzipped XML content

Example Resource Metadata:

{
  "name": "Samplers",
  "type": "GatewaySetup"
}

Example XML Content:

<gateway compatibility="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/GA3.0.0-121008/gateway.xsd">
  <samplers>
    <sampler name="Another CPU">
      <plugin>
        <cpu/>
      </plugin>
    </sampler>
  </samplers>
</gateway>

Get Resource Metadata Copied

GET /configuration/gateways/resources/{resourceId}

Returns the metadata associated with the requested resource.

Example Response:

{
  "id": 1,
  "name": "Samplers/Infrastructure",
  "hash": "f0ef7bbda8e1812f72bd2f2571d4bebe",
  "mainResource": false,
  "lastChangedBy": "John Doe",
  "lastChangedOn": "2023-01-01T10:00:00Z",
  "comment": "Add sampler",
  "type": "GatewaySetup",
  "usedBy": []
}

Get Resource Contents by ID Copied

GET /configuration/gateways/resources/{resourceId}/contents

Requests the contents of a setup resource as an XML document.

Response: XML content

Get Resource Contents by Name Copied

GET /configuration/gateways/resources/contents

Returns the XML contents of the resource that matches the resource name provided.

Example Request:

GET /configuration/gateways/resources/contents?name=Samplers.xml

Response: XML content

Delete Resource Copied

DELETE /configuration/gateways/resources/{resourceId}

Deletes a resource and all its history. This operation can only be performed by administrators and is irreversible.

Get Resource History Copied

GET /configuration/gateways/resources/{resourceId}/archives

Returns an ordered list of historic versions of the resource identified by the supplied resource ID.

Resource Locking Copied

Create Resource Locks Copied

POST /configuration/gateways/resources/locks

Locks one or more resources. Locking a resource ensures that no users other than the owner of the lock can modify the resource.

Request Body:

{
  "resources": [
    {
      "id": 1,
      "hash": "11d539978dea4b80e27dc6cc01ab06b0"
    }
  ],
  "force": true
}

Get Resource Locks Copied

GET /configuration/gateways/resources/locks

Returns a list of resource lock information.

Create Single Resource Lock Copied

POST /configuration/gateways/resources/{resourceId}/locks

Locks a resource. Locking a resource ensures that no users other than the owner of the lock can modify the resource.

Example Response:

{
  "id": 345,
  "createdOn": "2023-01-01T10:00:00Z",
  "expiresOn": "2023-01-01T10:30:00Z",
  "createdBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs"
  }
}

Get Resource Lock Copied

GET /configuration/gateways/resources/{resourceId}/locks

Returns the lock information for the resource with the supplied id.

Delete Resource Lock Copied

DELETE /configuration/gateways/resources/{resourceId}/locks

Unlocks a resource. Only the owner of the lock and administrators can unlock a resource.

Resource Permissions Copied

Get Resource Permissions Copied

GET /configuration/gateways/resources/{resourceId}/permissions

Retrieves the permissions for a gateway setup resource.

Example Response:

{
  "read": {
    "roles": ["admin", "engineering", "operator"]
  },
  "write": {
    "roles": ["admin", "engineering"]
  }
}

Update Resource Permissions Copied

PUT /configuration/gateways/resources/{resourceId}/permissions

Sets permissions on a gateway setup resource. This operation can only be performed by administrators.

Request Body:

{
  "read": {
    "roles": ["admin", "engineering", "operator"]
  },
  "write": {
    "roles": ["admin", "engineering"]
  }
}

Validation Management Copied

Validate Gateway Setup Copied

POST /configuration/gateways/{gatewayId}/validations

Validates changes to the resources of a gateway stored in Obcerv. The resources included in the request should be all the resources used by the gateway.

Request Body (JSON):

{
  "resources": [
    {
      "id": 1,
      "hash": "11d539978dea4b80e27dc6cc01ab06b0"
    }
  ]
}

Request Body (Multipart for XML contents):

• gatewaychanges: JSON with resource metadata
• {resourceId}: XML content for each resource

Example Response:

{
  "id": 10
}

Apply Gateway Setup Changes Copied

POST /configuration/gateways/{gatewayId}/changes

Applies changes to the resources of a gateway stored in Obcerv. The resources that are passed should be all the resources used by the gateway.

Request Body:

{
  "source": "Gateway Setup Editor",
  "comment": "Added new CPU sampler",
  "resources": [
    {
      "id": 1,
      "hash": "11d539978dea4b80e27dc6cc01ab06b0"
    }
  ]
}

Get Validation Status Copied

GET /configuration/gateways/validations/{validationId}

Returns information regarding the status of a pending gateway setup validation.

Example Response:

{
  "id": 10,
  "status": "DONE",
  "startTime": "2019-11-12T12:04:10Z",
  "endTime": "2019-11-12T12:08:10Z",
  "gatewaysValidated": 10,
  "gatewaysPending": 1,
  "abortMessage": "Aborted by user John Doe (jdoe)"
}

Get Validation Messages Copied

GET /configuration/gateways/validations/{validationId}/messages

Returns validation messages generated by the gateways that have been validated as part of a setup validation request.

Example Response:

{
  "validationMessages": [
    {
      "module": "SetupManager",
      "path": "/gateway/operatingEnvironment",
      "description": "Invalid reference to probe 'P1'",
      "gateway": {
        "id": 1,
        "name": "EMEA-Prod"
      },
      "resource": {
        "name": "Gateway/EMEA-Prod",
        "isMain": true
      },
      "severity": "Error"
    }
  ]
}

Abort Validation Copied

DELETE /configuration/gateways/validations/{validationId}

Aborts an ongoing gateway setup validation.

Data Schemas Copied

ApiError Copied

Standard error response format.

{
  "title": "Bad Request",
  "body": "Parameter 'name' must be set",
  "timestamp": "2022-10-1T10:01:10Z"
}

CurrentResource Copied

Current resource with detailed metadata.

{
  "id": 1,
  "name": "Samplers/Infrastructure",
  "hash": "f0ef7bbda8e1812f72bd2f2571d4bebe",
  "mainResource": false,
  "lastChangedBy": "John Doe",
  "lastChangedOn": "2023-01-01T10:00:00Z",
  "comment": "Add sampler",
  "type": "GatewaySetup",
  "usedBy": [1, 2, 3]
}

Gateway Copied

Represents a gateway configuration.

{
  "id": 1,
  "name": "EMEA/Infrastructure",
  "version": "GA4.7.1",
  "setupValidationId": 3
}

GatewayArtifactVersions Copied

List of available gateway artifact versions.

{
  "versions": ["GA5.7.1-230112", "GA6.1.0-230204"]
}

GatewayChangesQuery Copied

Request body for applying gateway setup changes.

{
  "source": "Gateway Setup Editor",
  "comment": "Added new CPU sampler",
  "resources": [
    {
      "id": 1,
      "hash": "11d539978dea4b80e27dc6cc01ab06b0"
    }
  ]
}

GatewayCreationQuery Copied

Request body for creating a new gateway.

{
  "name": "Gateway/EMEA",
  "version": "GA4.5.1-220111"
}

GatewayHistory Copied

Historical version of a gateway.

{
  "id": 1,
  "name": "EMEA/Infrastructure",
  "version": "GA4.7.1",
  "resources": [
    {
      "id": 1,
      "name": "Samplers/Infrastructure",
      "version": "2",
      "hash": "f0ef7bbda8e1812f72bd2f2571d4bebe",
      "mainResource": false
    }
  ],
  "setupValidationId": 3,
  "docVersion": "5"
}

GatewayValidationQuery Copied

Request body for validating gateway setup.

{
  "resources": [
    {
      "id": 1,
      "hash": "11d539978dea4b80e27dc6cc01ab06b0"
    }
  ]
}

GatewayWithResources Copied

Gateway with its associated resources.

{
  "id": 1,
  "name": "EMEA/Infrastructure",
  "version": "GA4.7.1",
  "resources": [
    {
      "id": 1,
      "name": "Samplers/Infrastructure",
      "version": "2",
      "hash": "f0ef7bbda8e1812f72bd2f2571d4bebe",
      "mainResource": false
    }
  ],
  "setupValidationId": 3
}

IdEntry Copied

Generic ID response.

{
  "id": 10
}

LockOwner Copied

Information about the owner of a resource lock.

{
  "username": "jbloggs",
  "displayName": "Joe Bloggs"
}

LocksCreationQuery Copied

Request body for creating multiple resource locks.

{
  "resources": [
    {
      "id": 1,
      "hash": "11d539978dea4b80e27dc6cc01ab06b0"
    }
  ],
  "force": true
}

Permission Copied

Permission definition with roles.

{
  "roles": ["admin", "engineering", "operator"]
}

Resource Copied

Represents a gateway resource.

{
  "id": 1,
  "name": "Samplers/Infrastructure",
  "version": "2",
  "hash": "f0ef7bbda8e1812f72bd2f2571d4bebe",
  "mainResource": false,
  "lastChangedBy": "John Doe",
  "lastChangedOn": "2023-01-01T10:00:00Z",
  "comment": "Add sampler",
  "type": "GatewaySetup",
  "usedBy": []
}

ResourceHistory Copied

Historical version of a resource.

{
  "lastChangedBy": "John Doe",
  "lastChangedOn": "2023-01-01T10:00:00Z",
  "hash": "f0ef7bbda8e1812f72bd2f2571d4bebe",
  "version": "1001",
  "comment": "Add Disk sampler"
}

ResourceInfo Copied

Basic resource information with ID and hash.

{
  "id": 345,
  "hash": "67fa6095466e46b70e2c9d50e82c626a"
}

ResourceLockInfo Copied

Information about a resource lock.

{
  "id": 345,
  "createdOn": "2023-01-01T10:00:00Z",
  "expiresOn": "2023-01-01T10:30:00Z",
  "createdBy": {
    "username": "jbloggs",
    "displayName": "Joe Bloggs"
  }
}

ResourcePermissions Copied

Resource permissions configuration.

{
  "read": {
    "roles": ["admin", "engineering", "operator"]
  },
  "write": {
    "roles": ["admin", "engineering"]
  }
}

ValidatedGateway Copied

Gateway information in validation context.

{
  "id": 1,
  "name": "EMEA-Prod"
}

ValidatedResource Copied

Resource information in validation context.

{
  "name": "Gateway/EMEA-Prod",
  "isMain": true
}

ValidationMessage Copied

A validation message from gateway validation.

{
  "module": "SetupManager",
  "path": "/gateway/operatingEnvironment",
  "description": "Invalid reference to probe 'P1'",
  "gateway": {
    "id": 1,
    "name": "EMEA-Prod"
  },
  "resource": {
    "name": "Gateway/EMEA-Prod",
    "isMain": true
  },
  "severity": "Error"
}

ValidationMessages Copied

Collection of validation messages.

{
  "validationMessages": [
    {
      "module": "SetupManager",
      "path": "/gateway/operatingEnvironment",
      "description": "Invalid reference to probe 'P1'",
      "gateway": {
        "id": 1,
        "name": "EMEA-Prod"
      },
      "resource": {
        "name": "Gateway/EMEA-Prod",
        "isMain": true
      },
      "severity": "Error"
    }
  ]
}

ValidationStatus Copied

Status information for a validation request.

{
  "id": 10,
  "status": "DONE",
  "startTime": "2019-11-12T12:04:10Z",
  "endTime": "2019-11-12T12:08:10Z",
  "gatewaysValidated": 10,
  "gatewaysPending": 1,
  "abortMessage": "Aborted by user John Doe (jdoe)"
}

VersionUpdateQuery Copied

Request body for updating gateway version.

{
  "version": "GA4.5.1-221010"
}