Rest API – CI Relationships
Overview
The REST API allows you to work with Configuration Items (CI) Relationships in FireScope SPM using a REST client in lieu of the SPM user interface.
- Retrieve
- Search
- Create or Update
- Delete
Retrieve
To retrieve the current information about a CIRelationship as a JSON document, send a GET request with the following URL format:
http://localhost:38050/web_services/ci_relationship?account=firescope&name={"account":"firescope","ci_relationship_category":"Application","servicegroup":"Dev Mongo Servers","port":30000,"source_ci":{"edge_device":"Prism Edge","ci":"devmongo3.firescope.int"},"target_ci":{"edge_device":"Prism Edge","ci":"devmongo1.firescope.int"}}
The name parameter is a JSON document. The expanded version of the JSON name document is :
name = {
"account":"prism",
"ci_relationship_category":"Application",
"servicegroup":"Dev Mongo Servers",
"port":30000,
"source_ci":{
"edge_device":"Prism Edge",
"ci":"devmongo3.firescope.int"
},
"target_ci":{
"edge_device":"Prism Edge",
"ci":"devmongo1.firescope.int"
}
}
Note that the account name appears twice. First as a primary HTTP parameter and second as the first element of the JSON name parameter.
All fields are required.
Note: Don’t forget to change the domain name (localhost) and query parameters (account, ci_relationship_category, servicegroup, port, source_ci, and target_ci) values to match your environment and data.
Search
Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.
http://localhost:38050/web_services/...ze=10&status=1
Note: Don’t forget to change the domain name (localhost) and query parameter (search, account, servicegroup, status, page and size ) values to match your environment and data.
Search Parameter Descriptions
Parameter | Description | Type | Default | Required |
account | Name of the SPM Account. | String | Yes | |
search | Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. | Boolean | FALSE | Yes |
page | Indicates which result set is being returned starting at zero and increasing until there are no more results | Number | 0 | Yes |
size | Indicates how many results are returned in a single page. A max of 250 results is supported. | Number | 100 | Yes |
servicegroup | Filter the results by a Service Group’s exact name. | String | No | |
status | Filter the results by status (0=”Pending”,1=”Approved”,2=”Rejected”) | Number | No |
Example Search Response
{
"account_id": "firescope",
"entity": "ci_relationship",
"page": 0,
"size": 2,
"results": [
{
"account_id": "firescope",
"ci_relationship_category_id": "Network",
"ci_relationship_type_id": "contains",
"pending_delete": True,
"port": 19234,
"protocol_name": "",
"protocol_type": "TCP",
"servicegroupid": "Ordering",
"source_ci": "esx1",
"status": 1,
"target_ci": "firescope.com"
}, {
"account_id": "firescope",
"ci_relationship_category_id": "Application",
"ci_relationship_type_id": "related",
"pending_delete": False,
"port": 80,
"protocol_name": "http",
"protocol_type": "TCP",
"servicegroupid": "Ordering",
"source_ci": "10.0.22.10",
"status": 0,
"target_ci": "firescope.com"
}
]
}
Create or Update
To create or update a CIRelationship, POST a JSON document with the specific CIRelationship information to the following URL:
http://localhost:38050/web_services/ci_relationship&name={"account":"firescope","ci_relationship_category":"Application","servicegroup":"Dev Mongo Servers","port":30000,"source_ci":{"edge_device":"Prism Edge","ci":"devmongo3.firescope.int"},"target_ci":{"edge_device":"Prism Edge","ci":"devmongo1.firescope.int"}}
You can use the following example as a guide, but note that it does not include all optional properties.
{
"account_id": "prism",
"last_flow_ts": 1589826430,
"pending_delete": 0,
"port": 30000,
"protocol_name": "ndmps",
"protocol_type": "TCP",
"ci_relationship_category_id": "Application",
"ci_relationship_type_id": "related",
"servicegroupid": "Mongo Servers",
"source_ci": {
"edge_device": "Prism Edge",
"ci": "devmongo3.firescope.int"
},
"status": 0,
"target_ci": {
"edge_device": "Prism Edge",
"ci": "devmongo1.firescope.int"
},
}
Property Descriptions
The following table provides information about all required and optional properties available for a CI Relationship.
Property | Description | Type | Default Value | Required |
account_id | Name of the SPM Account. | String | Yes | |
ci_relationship_category_id | Name of the category this relationship falls into:* ApplicationNetworkStorageVirtual | String | Yes | |
ci_relationship_type_id | The type of relationship indicates whether it is a parent/child relation or just a normal relationship.* containsrelated | String | Yes | |
pending_delete | Whether the relationship has been marked for deletion and awaiting user approval. | Boolean | False | Yes |
port | The port associated with this relationship. Usually this indicates the target server’s listening port. | Number | Yes | |
protocol_name | The application protocol name associated with this traffic. For example, http, ldap, etc. | String | No | |
protocol_type | The transport layer protocol. Either UDP or TCP. | String | Yes | |
servicegroupid | Name of the Service Group associated with the CI. | String | Yes | |
source_ci | The originating CI of the relationship. Example:{“edge_device_id” : “Datacenter East”, “ci” : “10.0.0.10”} | Object | Yes | |
status | Status of the relationship:0 = Pending1 = Approved2 = Rejected | Number | 0 | Yes |
target_ci | The destination CI of the relationship. Example:{“edge_device_id” : “Datacenter East”, “ci” : “10.0.0.20”} | Object | Yes |
Delete
To delete a CIRelationship, send an HTTP DELETE request with the same query parameters as the GET request. See the Retrieve for the URL format and query parameter descriptions.