Download OpenAPI specification: Download
Topology Exposure and Inventory data is the information that represents entities in a telecommunications network and the relationships between them that provide insight into a particular aspect of the network of importance to specific use cases. Topology and Inventory data can be derived from inventory, configuration, or other data.
Topology Exposure and Inventory supports several topology domains. A domain is a grouping of topology and inventory entities that handles topology and inventory data.
Entities are enabling the modelling and storage of complex network infrastructure and relationships.
A relationship is a bi-directional connection between two entities, one of which is the originating side (A-side) and the other is the terminating side (B-side). The order of the sides matters since it defines the relationship itself which must be unique.
Classifier (also known as tag or label) permits the association of a well defined user specified string with an entity or relationship.
Decorators are user-defined attributes (key-value pairs) which can be applied to topology entities and relationships.
Metadata provides additional information about entities and relationships within the database. The reliabilityIndicator is used to indicate the reliability status of the topology data within the network. The firstDiscovered timestamp is set for an entity and relationship instance when the instances are created for the first time in Topology & Inventory. The lastModified timestamp is set for updates to entities or relationships in Topology & Inventory, excluding updates to classifiers or decorators. reliabilityIndicator, firstDiscovered, and lastModified are implemented as name-value pairs within the metadata. They apply to every entity and relationship.
Topology groups provide the capability to create user-defined collections of topology entities and/or relationships of any type. Groups can be either static or dynamic based on how they are created.
Topology Exposure and Inventory API provides the capabilities to fetch topology data. Using the filtering options, it is possible to define more specific query requests.
The entityTypeName is used as the root of the queries (from here referred to as RootObject). Every other object, either in targetFilter or scopeFilter, has to relate to the RootObject. The queries are constructed starting from the RootObject and all other objects are joined to it. If there is no connection between the RootObject and the other object(s), the query is not constructed. The RootObject still can be retrieved and filtered using the /attributes.
| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|---|
| To return the ids for all instances of the entityTypeName used in the query. | RAN | ODUFunction | All ids of every ODUFunction | ||
| To return all attributes of every instance of the entityTypeName used in the query. | RAN | ODUFunction | /attributes | All ODUFunctions with every attribute | |
| To return every instance of the entityTypeName used in the query, but only the attribute that was defined in the targetFilter parameter. Note: The attribute must be a valid field of the object. | RAN | ODUFunction | /attributes(gNBId) | All gNBIds of every ODUFunction | |
| To return every instance of the entityTypeName used in the query, but only the attributes that were defined in the targetFilter parameter. Note: The attributes must be separated by a comma "," when using parenthesis "()". | RAN | ODUFunction | /attributes(gNBId, gNBIdLength) | All gNBIds and gNBIdLengths of every ODUFunction | |
| To return the ids for all instances of the entityTypeName used in the query, that partially matches the given property in the scopeFilter parameter. | RAN | ODUFunction | /sourceIds[contains (@item, 'SubNetwork=Europe')] | Unique set of ids of ODUFunctions, where sourceIds contains SubNetwork=Ireland | |
| To return the ids for all instances of the entityTypeName used in the query, that matches the given attributes in the scopeFilter parameter. Note: The attributes must be separated by a AND or OR. | RAN | ODUFunction | /attributes [@gNBIdLength=1 and @gNBId=9] | Unique set of ids of ODUFunctions, where the gNBIdLength equals 1 and the gNBId equals 9 | |
| To return the ids for all instances of the entityTypeName used in the query, that satisfies one of the conditions in the scopeFilter parameter. A condition is a complete unit of scopeFilter parameter surrounded by square brackets. Note: Multiple conditions can be given in the scopeFilter separated by a semicolon ";" to represent AND, or a pipe symbol "|" to represent OR. | RAN | ODUFunction | /attributes [@gNBIdLength=2] | /sourceIds[contains (@item, 'SubNetwork=Europe')] | Unique set of ids of ODUFunctions, where the gNBIdLength equals 2 or the sourceIds contains an item with "SubNetwork=Europe" | |
| To return the metadata for all instances of the entityTypeName used in the query, that is firstDiscovered within the given timeframe in the scopeFilter parameter. Note: The timestamps can be queried in any timezone. | RAN | ODUFunction | /metadata[@firstDiscovered>='2025-01-06T12:34:56.789+05:30' and @firstDiscovered<='2025-01-09T16:10:36.461565+05:30'] | Unique set of ids of ODUFunctions, where metadata contains firstDiscovered timestamp within the range '2025-01-06T12:34:56.789+05:30' and '2025-01-09T16:10:36.461565+05:30' |
The entityTypeName is used as the root of the queries.
| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|---|
| To return the ids for all instances of an entityTypeName related by an association. | REL_OAM_RAN | ENodeBFunction | /managed-by-managedElement | All ENodeBFunction entities that are managed by any Managed Element. | |
| To return the ids for all instances of an entityTypeName related by an association to another entity specified by its id. | REL_OAM_RAN | ENodeBFunction | /managed-by-managedElement [@id = 'urn:3gpp:dn: ManagedElement=1'] | All ENodeBFunction entities that are managed by the Managed Element urn:3gpp:dn: ManagedElement=1. | |
| To return the attributes for all instances of an entityTypeName related by one or more associations to other entities specified by their id. | REL_OAM_RAN | ENodeBFunction | /attributes | /attributes [@enbId=1] ; /managed-by-managedElement [@id='urn:3gpp:dn: ManagedElement=1'] | /managed-by-managedElement [@id='urn:3gpp:dn: ManagedElement=2'] ; /provided-euTranCell [@id='urn:3gpp:dn: ManagedElement=1, EUtranCell=2'] | All ENodeBFunction entities with enbId as 1, managed by the Managed Element urn:3gpp:dn: ManagedElement=1 or urn:3gpp:dn: ManagedElement=2, and provides EuTranCell urn:3gpp:dn: ManagedElement=1, EUtranCell=2. |
| To return the ids for all instances of an entityTypeName related by one or more associations to other entities whose attribute matches the given scopeFilter parameter. | RAN | ENodeBFunction | /provided-euTranCell/attributes[@tac=1] | All ENodeBFunction entities that provide an EUTranCell whose tac equals 1 |
The entityTypeName is used as the root of the queries. Use the "Well-known text" (WKT) representation of geometry to specify geometry objects.
| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|---|
| To return the ids for all instances of an entityTypeName where the given attribute is covered by the given polygon. | EQUIPMENT | AntennaModule | /attributes[coveredBy(@geo-location, 'POLYGON ((-73.958444 40.800533, -73.981962 40.768558, -73.973207 40.765048, -73.949861 40.797024, -73.958444 40.800533))')] | All AntennaModule entities covered by the given polygon. | |
| To return the attributes for all instances of an entityTypeName where the given attribute is covered by the given collection of polygons. | EQUIPMENT | AntennaModule | /attributes | /attributes[coveredBy(@geo-location, 'MULTIPOLYGON (((40 40, 20 45, 45 30, 40 40)),((20 35, 10 30, 10 10, 30 5, 45 20, 20 35), (30 20, 20 15, 20 25, 30 20)))')] | All AntennaModule entities covered by the given polygons. |
| To return the ids for all instances of an entityTypeName within the given distance in meters from a given attribute. | EQUIPMENT | AntennaModule | /attributes[withinMeters(@geo-location, 'POINT(-73.958444 40.800533)', 500.5)] | All AntennaModule entities within the given distance from the given point. | |
| To return the attributes for all instances of an entityTypeName which has a connected entity whose given attribute is within a polygon | RAN | NRCellDU | /attributes | /serving-antennaModule/attributes[coveredBy(@geo-location, 'POLYGON ((-73.958444 40.800533, -73.981962 40.768558, -73.973207 40.765048, -73.949861 40.797024, -73.958444 40.800533))')] | All NRCellDU entities that have at least one connected AntennaModule with a geo-location attribute within the given polygon. |
The entityTypeName is used as the root of the queries.
| Use case | domainName | entityTypeName | entityId | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|---|---|
| To return the relationships for a given entity specified by its id. | RAN | ODUFunction | urn:3gpp:dn: ManagedElement=1, ODUFunction=1 | All relations for the ODUFunction with id urn:3gpp:dn: ManagedElement=1, ODUFunction=1. | ||
| To return specific relationships for a given entity specified by its id. | REL_OAM_RAN | ODUFunction | urn:3gpp:dn: ManagedElement=1, ODUFunction=1 | /MANAGEDELEMENT _MANAGES _ODUFUNCTION | All MANAGEDELEMENT _MANAGES _ODUFUNCTION relations for the ODUFunction with id urn:3gpp:dn: ManagedElement=1, ODUFunction=1. | |
| To return specific relationships for an entity specified by its id to another entity using its id and association. | REL_OAM_RAN | ODUFunction | urn:3gpp:dn: ManagedElement=1, ODUFunction=1 | /managed-by-managedElement [@id = 'urn:3gpp:dn: ManagedElement=1'] | All MANAGEDELEMENT _MANAGES _ODUFUNCTION relations for the ODUFunction with id urn:3gpp:dn: ManagedElement=1, ODUFunction=1 where the managed element is urn:3gpp:dn: ManagedElement=1. |
Here, the relationshipTypeName is used as the root of the queries.
| Use case | domainName | relationshipTypeName | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|---|
| To return all relationships for a specified relationship type. | REL_OAM_RAN | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION relationships. | ||
| To return all relationships for a specified relationship type with a specified association to an entity. | REL_OAM_RAN | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | /managed-by-managedElement [@id='urn:3gpp:dn: ManagedElement=1'] | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION relationships having an association managed-by-managedElement to ManagedElement urn:3gpp:dn: ManagedElement=1. |
The domainName is used as the root of the queries.
| Use case | domainName | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|
| Return all related entity ids that are exactly matched with the specified classifier with given domain name. | RAN | /classifiers[@item = 'odu-function-model:Indoor'] | All the entity ids that are classified with "odu-function-model:Indoor" in RAN domain. | |
| Return all related entity ids that are partially matched for the given classifier with given domain name. | RAN | /classifiers[contains(@item, 'Ind')] | All the entity ids that are partially matched with "Ind" in RAN domain. | |
| Return all related entity ids that are exactly matched with the key-value pair that specified decorators with given domain name. | RAN | /decorators[@odu-function-model:textdata = 'Stockholm'] | All the entity ids that are exactly matched with "odu-function-model:textdata = 'Stockholm'" in RAN domain. | |
| Return all related entity ids that are exactly matched with key parameter where the value of the decorator is unknown with given domain name. | RAN | /decorators[contains(@odu-function-model:textdata, '')] | All the entity ids that are exactly matched with "odu-function-model:textdata as key of the decorator in RAN domain. |
The entityName is used as the root of the queries.
| Use case | entityName | relationshipTypeName | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|---|
| Return all related entity ids and classifiers. | NRCellDU | /classifiers | All NRCellDU ids and classifiers. | ||
| Return all related entity ids and decorators. | NRCellDU | /decorators | All NRCellDU ids and decorators. | ||
| Return all related entity ids that are exact match for the given classifiers and decorators. | NRCellDU | /classifiers[@item = 'odu-function-model:Indoor']; /decorators [@odu-function-model:textdata = 'Stockholm'] | All NRCellDU ids where key of the decorator is "odu-function-model:textdata" and the value of the decorator is 'Stockholm'" and where classifier exactly contains "odu-function-model:Indoor". | ||
| Return all related entity ids and classifiers that are partially matched for the given classifier. | NRCellDU | /classifiers | /classifiers[contains(@item, 'Ind')] | All NRCellDU ids and classifiers partially contains the text "Ind". | |
| Return all related entity ids and decorators where key is a exact match and value is partially match. | NRCellDU | /decorators | /decorators[contains(@odu-function-model:textdata, 'Stoc')] | All NRCellDU ids and where key of the decorator is "odu-function-model:textdata" and the value of the decorator partially contains 'Stoc'. | |
| Return all related entity ids, decorators and classifiers where key of the decorator is a exact match and value partially matches, and classifiers partially contains from the given parameters. | NRCellDU | /classifiers; /decorators | /classifiers[contains(@item, 'Ind')]; /decorators[contains(@odu-function-model:textdata, 'Stoc')] | All NRCellDU ids and decorators where key of the decorator is "odu-function-model:textdata" and the value of the decorator partially contains 'Stoc' and classifiers partially contains the text "Ind". |
The relationshipTypeName is used as the root of the queries.
| Use case | entityName | relationshipTypeName | targetFilter | scopeFilter | Query result |
|---|---|---|---|---|---|
| Return all related relationship ids and classifiers. | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | /classifiers | All MANAGEDELEMENT _MANAGES _ENODEBFUNCTION ids and classifiers. | ||
| Return all related relationship ids and decorators. | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | /decorators | All MANAGEDELEMENT _MANAGES _ENODEBFUNCTION ids and decorators. | ||
| Return all related relationship ids that are exact match for the given classifier and decorators. | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | /classifiers[@item = 'odu-function-model:Indoor']; /decorators [@odu-function-model:textdata = 'Stockholm'] | All MANAGEDELEMENT _MANAGES _ENODEBFUNCTION ids and decorators where key of the decorator is "odu-function-model:textdata" and the value of the decorator is 'Stockholm'" and classifiers exactly contains "odu-function-model:Indoor". | ||
| Return all related relationship ids and classifiers that are partially matched for the given classifier. | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | /classifiers | /classifiers[contains(@item, 'Ind')] | All MANAGEDELEMENT _MANAGES _ENODEBFUNCTION and classifiers partially contains the text "Ind". | |
| Return all related relationship ids and decorators where key is a exact match and value is partially match. | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | /decorators | /decorators[contains(@odu-function-model:textdata, 'Stock')] | All MANAGEDELEMENT _MANAGES _ENODEBFUNCTION and where key of the decorator is "odu-function-model:textdata" and the value of the decorator partially contains 'Stock'. | |
| Return all related relationship ids,decorators and classifiers where key of the decorator is a exact match and value partially matches, and classifiers partially contains from the given parameters. | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | /classifiers; /decorators | /classifiers[contains(@item, 'Ind')]; /decorators[contains(@odu-function-model:textdata, 'Stock')] | All MANAGEDELEMENT _MANAGES _ENODEBFUNCTION ids and decorators where key of the decorator is "odu-function-model:textdata" and the value of the decorator partially contains 'Stock' and classifiers partially contains the text "Ind". |
Provides the capability to retrieve topology and inventory entities and relationships.
Get all the available topology domains.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error
Get all the available topology entity types in domain name.
domain name
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error
Get all topology entities of a specific entity type.
domain name
Use targetFilter to specify what needs to be returned in the REST response.
ScopeFilter is used to specify the conditions to be applied.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error
Get topology for entity type name with specified id. Specified id represents the entity instance.
domain name
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
Get all relationships for entity type name with specified id. Specified id represents the entity instance.
domain name
Use targetFilter to specify what needs to be returned in the REST response.
ScopeFilter is used to specify the conditions to be applied.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
Get all the available topology relationship types in a specified domain.
domain name
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error
Get topology relationships of a specific relationship type name.
domain name
Use targetFilter to specify what needs to be returned in the REST response.
ScopeFilter is used to specify the conditions to be applied.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error
Get relationship with specified id. Specified id represents the relationship instance.
domain name
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
Get topology entities by domain, using a specified targetFilter as a query parameter.
domain name
Use targetFilter to specify what needs to be returned in the REST response.
ScopeFilter is used to specify the conditions to be applied.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error
Schemas are defined in YANG modeling language. A group of Yang schemas makes the topology and inventory model, which represents topology and inventory entities, their attributes, and their relationships. For more information on YANG modelling language, see IETF Documentation.
Create a new schema. The request body contains the schema in YANG format.
201 Created without response body
400 Bad Request
401 Unauthorized
403 Forbidden
409 Conflict
500 Internal Server Error
Get a list of all schemas.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error
Provides the capability to update or remove user-defined keywords or tags on entities and relationships.
Update entities and/or relationships with classifier(s). The sum of the given entityIds and relationshipIds cannot exceed 100 by default.
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
409 Conflict
500 Internal Server Error
Provides the capability to update or remove user-defined values on entities and relationships.
Update entities and/or relationships with decorator(s). The sum of the given entityIds and relationshipIds cannot exceed 100 by default.
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
409 Conflict
500 Internal Server Error
Provides the capability to group topology entities and/or relationships of any type. Groups can be created in static or dynamic way. Static groups: Group members are defined statically upon group creation. It can include a maximum of 10,000 members. Dynamic groups: Group members are dynamically selected based on the defined resource query.
Get all groups.
Pagination offset.
Result limiter.
Group name. If not specified, returns all the groups.
200 OK
400 Bad Request
500 Internal Server Error
Get the members of a group with specified id.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error
Get the provided members of a static group with specified id.
Status can be present (or) not-present (or) invalid. If not specified, returns all members of the group.
Pagination offset.
Result limiter.
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error
Merge or remove members in an existing topology group. This operation is applicable for static group only.
204 No Content
400 Bad Request
500 Internal Server Error