#### TMF API Reference: [TMF620 - Product Catalog Management](https://www.tmforum.org/resources/standard/tmf620-product-catalog-management-api-user-guide-v4-1-0/) Product Catalog API is one of Catalog Management API Family. Product Catalog API goal is to provide a catalog of products. #### Operations Product Catalog API performs the following operations on the ProductOffering and ProductOfferingPrice resources: - Retrieve an entity or a collection of entities depending on filter criteria - Partial update of an entity - Create an entity - Delete an entity

HTTP Query

API supports attribute filtering using http query, f.e.: `.../attachment?id=123` Key-value pairs can be connected with '&' (AND operation) and/or ';' (OR operation). All consecutive OR operations automatically grouped into one single group, f.e.: `.../attachment?id=123&name=n1;description=n2&status=3` means `(id = 123) and (name = 'n1' or description = 'n2') and (status = 3)` Comma-separated values converted into a list of values connected with OR operator, f.e.: `.../attachment?id=123&name=n1,n2,n3&status=3` means `(id = 123) and (name = 'n1' or name = 'n2' or name = 'n3') and (status = 3)` Besides an equal comparison the API supports a list of two different notations of some other operations including regular expressions (you can mix both notations in the same query), f.e: `.../attachment?name.regex=/^n/i&status>=3&startDate.gt=2022-01-01` means `(name ~= /^n/i) and (status >= 3) and (startDate > Date('2022-01-01'))` *API converts incoming string values to a specific types according to an internal DB Schema, f.e. in this case if startDate is defined as Date the string '2022-01-01' will be converted into date automatically before the comparison.* ##### Supported operators: |Operators|Description |---|--------- | & | Logical AND | ; | Logical OR | , | Logical OR between values of the same property ##### Supported operations: |Notation A|Notation B|Description |---|---|--- | = | .eq | Matches values that are equal to a specified value. | != | .ne | Matches all values that are not equal to a specified value. | > | .gt | Matches values that are greater than a specified value. | >= | .gte | Matches values that are greater than or equal to a specified value. | < | .lt | Matches values that are less than a specified value. | <= | .lte | Matches values that are less than or equal to a specified value. | =~ | .regex | Selects documents where values match a specified regular expression. Use URI-component encoding for values to avoid misinterpretation. ##### See more details about operators and syntax in [TMF630 REST API Design and Guidelines Part One](https://www.tmforum.org/resources/specification/tmf630-rest-api-design-guidelines-4-2-0/)

Extended Query

API supports native MongoDB queries with limited number of supported operators. The query can be defined right in the http query as it is (use URI-component encoding and the query must be just a valid MongoDB JSON expression, no need to format the JSON into one single line without spaces). Multiple native queries are supported as well as http queries in any combinations, connect them with '&' or ';': `.../attachment?id=123;{"id":{"$exists":true}}&{"name":{"$exists":false}}` or the same URL after URI-encoding: `.../attachment?id=123;%7B%22id%22%3A%7B%22%24exists%22%3Atrue%7D%7D&%7B%22name%22%3A%7B%22%24exists%22%3Afalse%7D%7D` ##### Supported operators: |Operators|Description |---|--------- | Logical operators| | $and | Joins query clauses with a logical AND returns all documents that match the conditions of both clauses. | $not | Inverts the effect of a query expression and returns documents that do not match the query expression. | $nor | Joins query clauses with a logical NOR returns all documents that fail to match both clauses. | $or | Joins query clauses with a logical OR returns all documents that match the conditions of either clause. | Comparison operators| | $eq | Matches values that are equal to a specified value. | $gt | Matches values that are greater than a specified value. | $gte | Matches values that are greater than or equal to a specified value. | $in | Matches any of the values specified in an array. | $lt | Matches values that are less than a specified value. | $lte | Matches values that are less than or equal to a specified value. | $ne | Matches all values that are not equal to a specified value. | $nin | Matches none of the values specified in an array. | Element Operators | | $exists | Matches documents that have the specified field. | $type | Selects documents if a field is of the specified type. | Evaluation Operators | | $regex | Selects documents where values match a specified regular expression. | $text | Performs full-text search (only if server supports it) | Array Operators | | $all | Matches arrays that contain all elements specified in the query. | $elemMatch | Selects documents if element in the array field matches all the specified $elemMatch conditions. | $size | Selects documents if the array field is a specified size. | Miscellaneous Operators | | $rand | Generates a random float between 0 and 1. ##### See more details about operators and syntax in [MongoDB Query Operators](https://www.mongodb.com/docs/manual/reference/operator/query/)

Depth and Expand Directive

A common use case is to query a resource and “dereference” or “embed” the hyperlinked resource representations. This is achieved by issuing a GET with the DEPTH directive and or an EXPAND parameter. ##### Depth Directive The GET /api//?depth=n operation is used to expand inline the referenced data up to the level of the specified depth level. The “depth” is used to expand the level of referenced (related) entities such as bundled offerings and “target” references of relations. If depth = 0, then all referenced entities just RootEntity objects which contains only ID and @type (may contain name and href). If depth = 1, then the first level of related target entities is expanded. References are replaced with the actual loaded entities with the corresponding level of details. If depth = N it expands reference objects of related entities recursively. The last level contains only the references. ##### Expand Directive “expand” parameter is used to narrow down (filter) expanding of the referenced objects. If expand is not specified, then by default all the paths should be expanded. If the expand parameter is specified, only those paths should be expanded according to depth parameter. If depth is not specified, then the default value will depend on the expand parameter. If expand parameter is set, then depth is 1. If not set, then 0. In the following example the relatedParty at the root level of the productOffering is expanded up to 3 levels (relatedParty is the first level, all child objects are the second level and all grandchild objects are the third level), and all objects of productSpecification.resourceSpecification (grandchildren of productSpecification) are expanded up to 1 level: ```GET /productOffering/233452345?depth=3&expand=productSpecification.resourceSpecification,relatedParty``` If the chain of properties is longer then the depth value the rest of the chain is ignored. ``` DEPTH is a very time consuming operation, even depth=2 on a list of a few product offerings may trigger hundreds internal API calls to retrieve all required objects. Always use EXPAND directive to narrow the result to a minimally required data set. ```

JSONPath Query

API supports JSONPath filtering. Filter query parameter can be used to get a specific part of the retrieved objects. f.e. `filter=$[?(@property == 'id' && @ == '618a9586b4fa4f085c3d41b3')]` (use URI-component encoding) ##### See more details about operators and syntax in [JSONPath Guide](https://goessner.net/articles/JsonPath/)

#### Relationships

Supported relationships types via Product Offering API's

Relationship Type	Forward Relationship	Reverse Relationship
add-on	isAddOnFor	hasAddOn
swap	swapTo	isSwappableFrom
incompatibility	incompatible with	incompatible with