Query API examples

Retrieving and using topology modules

Topology & Inventory provides APIs to enable users query module data that can be used to understand the existing topology and inventory model,parse the modules, and understand what objects are supported over the R1 interface, so adequate queries can be made on topology and inventory data.

The API endpoints returning lists support pagination. The default value for number of items returned is 500, which is also the upper limit.

Sample request to fetch a list of all modules:

GET https://<host>/topology-inventory/<API_VERSION>/schemas

To get a list of all modules for a specific domain, use a domain query parameter. For example, /schemas?domain=<domain>

Sample request to fetch a list of all modules related to the RAN domain:

GET https://<host>/topology-inventory/<API_VERSION>/schemas?domain=ran

Note: - Partial matches are also supported in the query parameter using the ’*’ symbol as a wild card. - If the specified domain does not exist, an empty list is returned.

To get a specific module, supply a module name in the path parameter. For example, /schemas/<name>/content

Sample request to fetch the module data for the o-ran-smo-teiv-ran module:

GET https://<host>/topology-inventory/<API_VERSION>/schemas/o-ran-smo-teiv-ran/content

Note: If the specified module does not exist, an INVALID_MODULE_NAME error is returned.

Reading and querying topology and inventory

Reading entities and relationships

To get a list of all entities with all properties in a specified domain name, use: > /domains/{domainName}/entities

Example: Get all entities in the RAN domain:

GET https://<host>/topology-inventory/<API_VERSION>/domains/RAN/entities

To get a list of all available entity types in a specified domain name, use: > /domains/{domainName}/entity-types

Example: Get all entity types in the RAN domain:

GET https://<host>/topology-inventory/<API_VERSION>/domains/RAN/entity-types

To get a list of all available relationship types in a specified domain name, use: > /domains/{domainName}/relationship-types

Example: Get all relationship types in the RAN domain:

GET https://<host>/topology-inventory/<API_VERSION>/domains/RAN/relationship-types

Querying entities and relationships

Use the targetFilter parameter to narrow down the fields to return. To filter the results which match a given criteria, use the scopeFilter. Think of it as an SQL statement, where the targetFilter is the SELECT, and the scopeFilter is the WHERE tag.

A detailed explanation about the targetFilter and scopeFilter parameters can be found in Supported filter options.

Example:

In this example, the user is only interested in NRCellDU entities. Moreover, the user only wants those records that have sourceIds containing “SubNetwork=Ireland”. These fields and filters can be defined in the request as follows:

Parameters: - targetFilter: /NRCellDU - scopeFilter: /sourceIds[contains(@item,’SubNetwork=Ireland’)]

GET https://<host>/topology-inventory/<API_VERSION>/domains/RAN?targetFilter=/NRCellDU&scopeFilter=/sourceIds[contains(@item,'SubNetwork=Ireland')]

Note: If the targetFilter is not used here, the result contains all entities and relationships that matches the condition in the RAN domain.

Querying on geographical information examples

Topology & Inventory supports querying entities based on geographical information by updating the filters. Use the “Well-Known Text” (WKT) representation of geometry to specify geometry objects. The WKT representation of coordinate systems is a text markup language standard for representing vector geometry objects. For more information, see the WKT documentation

NOTE: This filter option is restricted to entities that have been enriched with geographical data.

Topology & Inventory supports the following geometric objects:

POINT: This can be used with the withinMeters function. It requires the latitude and longitude of the point and then a range in meters. It returns the desired objects within the provided distance in meters from the given point.

Example: Get all entities with geographical information in the ‘EQUIPMENT’ domain within 500 meters from a point with latitude and longitude values of 49.40199 and 68.94199 respectively:

` GET https://<host>/topology-inventory/<API_VERSION>/domains/EQUIPMENT/entities?scopeFilter=/attributes[withinMeters(@geo-location, 'POINT(49.40199 68.94199)', 500)] `

POLYGON: This can be used with the coveredBy function. It requires the latitude and longitude of the points of the polygon. It returns the desired objects covered by the given polygon.

Example: Get all ‘AntennaModule’ entities covered by the polygon with points (48 68) , (50 68), (50 69), (48 69), and (48 68):

` GET https://<host>/topology-inventory/<API_VERSION>/domains/EQUIPMENT/entity-types/AntennaModule/entities?scopeFilter=/attributes[coveredBy(@geo-location, 'POLYGON((48 68, 50 68, 50 69, 48 69, 48 68))')] `

NOTE: To draw a valid polygon, the first and last points must be identical.