Advanced Search

This page provides a comprehensive guide for searching within service items and change instances through declarations. It is possible to filter service items and change instances using specific data in their declarations provided in the URL's filter parameters. The value of these filter parameters is a dictionary where the key corresponds to the key defined in the service schema, and the value is the proposed search value.

Therefore, the format of the GET url with the query looks like:

<url>/?declaration={key: value}

Here, a list of examples is provided. Assume there are two services, VM and LoadBalancer, with the following schemas:

- VM:
  {
    `name`: `str`,
    `cpu`: `int`,
    `ram`: `int`
  }
- LoadBalancer:
  {
    `name`: `str`
    `related_vms`: [`array of strings`]
    `algorithm`: `str`
  }

Service items

You can use three filter parameters with service_items/? endpoint to filter the service items based on their latest declaration:

• /?declaration={} : To search for exact key values
• /?declaration_regex={} : To search in values using regex
• /?declaration_contains={} : Mostly to search in lists

Examples

Query	Description
/service_items/?	See all service items
/service_items/?declaration_regex={"name": "LB"}	Regex search where values contain the letters 'LB'
/service_items/?declaration_regex={"name": "^.{4}V.{0}"}	Results are service items with the letter "V" as the 4th letter in their names, e.g., "Core{V}MX"
/service_items/?declaration={"name": "CoreVM1"}	Only those with name exactly equals to "CoreVM1"
/service_items/?declaration={"related_vms": ["CoreVM1"]}	If there are two load balancers, one with "related_vms": ["CoreVM1"] and one with "related_vms": ["CoreVM1", "CoreVM2"], only one item is returned due to the exact match
/service_items/?declaration={"cpu": 122}	Only those service items which have "cpu" as key and 122 as value
/service_items/?declaration={"related_vms": []}	Returns the load balancers with an empty list
/service_items/?declaration={"related_vms": ["CoreVM1", "CoreVM2"]}	Returns the load balancers which has exactly both VMs in their "related_vms"
/service_items/?declaration_contains={"related_vms": ["CoreVM1"]}	Returns both load balancers which have at least "CoreVM1" in "related_vms"
/service_items/?declaration_contains={"related_vms": []}	Returns all items which have "related_vms" key in their declaration because all contain an empty list

Change Instances

Each change instance contains a new declaration for its service item except DELETE change instances. Similar to the service items endpoint, three new filter parameters are available:

• /?declaration={} : To search for exact key values
• /?declaration_regex={} : To search values using regex
• /?declaration_contains={} : Mostly to search in lists

Note: Since DELETE change instances don't have any new declaration, they will always be excluded

Examples:

Query	Description
/change_instances/?	See all change instances
/change_instances/?change_type=CREATE	Returns only CREATE change instances
/change_instances/?declaration_regex={"name": "PR019"}	Regex search where "name" field contains 'PR019'
/change_instances/?declaration_regex={"name": "^.{4}V.{0}"}	Results are change instances with the letter "V" as the 4th letter in their names, e.g., "Core{V}MX"
/change_instances/?declaration_regex={"name": "^.{4}V.{0}"}&change_type=CREATE	Results are CREATE change instances with the letter "V" as the 4th letter in their names
/change_instances/?declaration_regex={"name": "^.{4}V.{0}"}&exclude_referenced=true	Results are non-referenced change instances with the letter "V" as the 4th letter in their names
/change_instances/?declaration={"name": "CoreVM1"}	Returns change instances of service items with the exact name "CoreVM1" defined in the declaration
/change_instances/?declaration={"related_vms": ["CoreVM1"]}	Returns change instances with only "CoreVM1" in the related_vms array
/change_instances/?declaration={"cpu": 10}	Returns the change instances where the field "cpu" was modified to 10
/change_instances/?declaration={"related_vms": []}	Returns the change instances with an empty "related_vms" list
/change_instances/?declaration={"related_vms": ["CoreVM1", "CoreVM2"]}	Returns the change instances with an empty "related_vms" list
/change_instances/?declaration_contains={"related_vms": ["CoreVM1"]}	Returns change instances that contain "CoreVM1" in the "related_vms" field
/change_instances/?declaration_contains={"related_vms": []}	Returns all change instances that have the "related_vms" field in the declaration, regardless of the values