26.0 Collectors Configuration APIs

WAS THIS PAGE HELPFUL? Leave Feedback

26.1 List Collectors Configuration Files

List all available YAML Collectors Configuration file names. File names include the ".yaml" extension and are returned in case insensitive alphabetical order.

26.1.1 Method: GET all Collectors Configuration File Names

GET /api/collectors/configurations

26.1.2 HTTP Headers
Header Valid Values Required
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.1.3 HTTP Status Codes
Code Description
200 Collectors Configuration file names returned
401 Authentication/authorization error occurred
404 No Collectors Configuration files found
500 An internal server error occurred during get
26.1.4 File Names Responses

File names are returned as a list of strings in the standard XML and JSON wrapped forms.

<files>
    <file>config.yaml</file>
    <file>config2.yaml</file>
</files>
{
  "files" : [ "config.yaml", "config2.yaml" ]
}
26.2 Get Collectors Configuration File

Get YAML Collectors Configuration file content. File name must include the ".yaml" extension.

26.2.1 Method: GET Collectors Configuration File

GET /api/collectors/configurations/{fileName}

26.2.2 Path Parameters
Field Type Description Required
fileName Path File name including the ".yaml" extension yes
26.2.3 HTTP Headers
Header Valid Values Required
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.2.4 HTTP Status Codes
Code Description
200 Collectors Configuration content returned
400 Invalid Collectors Configuration file name
401 Authentication/authorization error occurred
404 Collectors Configuration file not found
500 An internal server error occurred during get
26.2.5 YAML Collectors Configuration Response

UTF-8 YAML Collectors Configuration is returned. Content type is text/yaml;charset=UTF-8.

26.3 Create Collectors Configuration File

Create YAML Collectors Configuration file from template. File name must include the ".yaml" extension. Accepts a number of identity properties that are merged into the template to create the file. Template is selected using the agentType and prefix identity properties.

26.3.1 Method: POST Create Collectors Configuration File

POST /api/collectors/configurations/{fileName}

26.3.2 Path And POST Parameters
Field Type Description Required
fileName Path File name including the ".yaml" extension yes
agentType* POST Collector agent type yes
prefix* POST Collector Configuration prefix yes
hostName POST Collector host name yes
ipv4 POST Collector address no
ipv6 POST Collector address no
mac POST Collector mac address no
characteristic POST Collector characteristic string no

* agentType and prefix parameters are used to select the Collectors Configuration template to instantiate.

26.3.3 POST Request

POST parameters are specified using the standard form/url encoded syntax.

agentType=child&prefix=child&hostName=localhost
26.3.4 HTTP Headers
Header Valid Values Required
Content-Type application/x-www-form-urlencoded True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.3.5 HTTP Status Codes
Code Description
200 Created Collectors Configuration content returned
400 Invalid Collectors Configuration file name or missing POST parameters
401 Authentication/authorization error occurred
404 Collectors Configuration template file not found
500 An internal server error occurred during create
26.3.6 YAML Collectors Configuration Response

Created UTF-8 YAML Collectors Configuration from template is returned. Content type is text/yaml;charset=UTF-8. YAML Collectors Configurations created with this endpoint will always contain an identity section.

identity:
    agentType: child
    prefix: child
    hostName: localhost
...
26.4 Add or Replace Collectors Configuration File

Add or replace YAML Collectors Configuration file. File name must include the ".yaml" extension. Accepts YAML file with multiple top level properties or sections, (i.e. can be loaded into a key/value pair). This endpoint does not return any content: 204 No Content is the successful return status.

26.4.1 Method: PUT Collectors Configuration File

PUT /api/collectors/configurations/{fileName}

26.4.2 Path Parameters
Field Type Description Required
fileName Path File name including the ".yaml" extension yes
26.4.3 PUT Request

UTF-8 YAML Collectors Configuration file content. Content type must be specified as text/yaml or application/x-yaml. If specified, charset must be set to UTF-8. Typically Collectors Configurations include an identity section.

identity:
    agentType: child
    prefix: child
    hostName: localhost
...
26.4.4 HTTP Headers
Header Valid Values Required
Content-Type text/yaml or application/x-yaml, charset=UTF-8 True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.4.5 HTTP Status Codes
Code Description
204 Collectors Configuration file added or replaced
400 Invalid Collectors Configuration file name or content
401 Authentication/authorization error occurred
500 An internal server error occurred during add or replace
26.5 Delete Collectors Configuration File

Delete existing YAML Collectors Configuration file. File name must include the ".yaml" extension. This endpoint does not return any content: 204 No Content is the successful return status.

26.5.1 Method: DELETE Collectors Configuration File

DELETE /api/collectors/configurations/{fileName}

26.5.2 Path Parameters
Field Type Description Required
fileName Path File name including the ".yaml" extension yes
26.5.3 HTTP Headers
Header Valid Values Required
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.5.4 HTTP Status Codes
Code Description
204 Collectors Configuration file deleted
400 Invalid Collectors Configuration file name
401 Authentication/authorization error occurred
500 An internal server error occurred during delete
26.6 List Collectors Configuration Template Files

List all available YAML Collectors Configuration template file names. File names include the ".yaml" extension and are returned in case insensitive alphabetical order.

26.6.1 Method: GET all Collectors Configuration Template File Names

GET /api/collectors/templates

26.6.2 HTTP Headers
Header Valid Values Required
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.6.3 HTTP Status Codes
Code Description
200 Collectors Configuration template file names returned
401 Authentication/authorization error occurred
404 No Collectors Configuration template files found
500 An internal server error occurred during get
26.6.4 File Names Responses

File names are returned as a list of strings in the standard XML and JSON wrapped forms.

<files>
    <file>config-template.yaml</file>
    <file>config-template2.yaml</file>
</files>
{
  "files" : [ "config-template.yaml", "config-template2.yaml" ]
}
26.7 Get Collectors Configuration Template File

Get YAML Collectors Configuration template file content. File name must include the ".yaml" extension.

26.7.1 Method: GET Collectors Configuration Template File

GET /api/collectors/templates/{fileName}

26.7.2 Path Parameters
Field Type Description Required
fileName Path File name including the ".yaml" extension yes
26.7.3 HTTP Headers
Header Valid Values Required
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.7.4 HTTP Status Codes
Code Description
200 Collectors Configuration template content returned
400 Invalid Collectors Configuration template file name
401 Authentication/authorization error occurred
404 Collectors Configuration template file not found
500 An internal server error occurred during get
26.7.5 YAML Collectors Configuration Response

UTF-8 YAML Collectors Configuration template is returned. Content type is text/yaml;charset=UTF-8.

26.8 Add or Replace Collectors Configuration Template File

Add or replace YAML Collectors Configuration template file. File name must include the ".yaml" extension. Template YAML Collectors Configurations must contain a top level identity section with agentType and optionally prefix sub key/values pairs. This minimal information is used to select templates when Collectors Configurations are created. This endpoint does not return any content: 204 No Content is the successful return status.

26.8.1 Method: PUT Collectors Configuration File

PUT /api/collectors/templates/{fileName}

26.8.2 Path Parameters
Field Type Description Required
fileName Path File name including the ".yaml" extension yes
26.8.3 PUT Request

UTF-8 YAML Collectors Configuration template file content. Content type must be specified as text/yaml or application/x-yaml. If specified, charset must be set to UTF-8. Collectors Configuration templates include an identity section with agentType and optionally prefix sub key/values pairs.

identity:
    agentType: child
    prefix: child
    hostName: localhost
...
26.8.4 HTTP Headers
Header Valid Values Required
Content-Type text/yaml or application/x-yaml, charset=UTF-8 True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.8.5 HTTP Status Codes
Code Description
204 Collectors Configuration template file added or replaced
400 Invalid Collectors Configuration template file name or content
401 Authentication/authorization error occurred
500 An internal server error occurred during add or replace
26.9 Delete Collectors Configuration Template File

Delete existing YAML Collectors Configuration template file. File name must include the ".yaml" extension. This endpoint does not return any content: 204 No Content is the successful return status.

26.9.1 Method: DELETE Collectors Configuration Template File

DELETE /api/collectors/templates/{fileName}

26.9.2 Path Parameters
Field Type Description Required
fileName Path File name including the ".yaml" extension yes
26.9.3 HTTP Headers
Header Valid Values Required
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
26.9.4 HTTP Status Codes
Code Description
204 Collectors Configuration template file deleted
400 Invalid Collectors Configuration template file name
401 Authentication/authorization error occurred
500 An internal server error occurred during delete