Open APIs

 View Only
  • 1.  TMF 680 API v4.0.0 API Specification and Conformance Profile

    TM Forum Member
    Posted Jan 09, 2020 15:46
    Hi Members,

    Could anyone please point me to supporting API specification and conformance profile for v4 of TMF 680 ? The latest documents are that of version 2.0.

    Further, is there a consolidated public repository where all TMF resource schemas (YML/JSON)  are present ? In order to create an extension ready reference to pre-defined base type schemas will be handy (Example : In context of Recommendation API - ProductOrder,ShoppingCart,Product Offering,Channel entities are of interest but there is no single repository where scheme for these resources are consolidated.)


    ------------------------------
    Indranil RoyChowdhury
    Ericsson Inc.
    ------------------------------


  • 2.  RE: TMF 680 API v4.0.0 API Specification and Conformance Profile

    TM Forum Member
    Posted Jan 13, 2020 04:58
    Please refer to my answer to your other post
    https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?GroupId=31&MessageKey=a35bbca0-1021-4866-941f-22b2c6621029&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer&ReturnUrl=%2fcommunities%2fcommunity-home%2fdigestviewer%3fcommunitykey%3dd543b8ba-9d3a-4121-85ce-5b68e6c31ce5%26tab%3ddigestviewer
    There is not currently a public repository with the Open API schemas. API Program leads such as @Steve Harrop and @Ludovic Robert might be able to give more visibility regarding possible publication of the schemas.


    ​​

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: TMF 680 API v4.0.0 API Specification and Conformance Profile

    TM Forum Member
    Posted Jan 14, 2020 17:29
    Hi @Jonathan Goldberg , thank you for confirming, however, I also came across this repository https://github.com/tmforum-rand/schemas/tree/R19.0 where all JSON schemas seem to be have been stored. I could see some reference to it in other posts as well.

    What relation does these schema files have with the schema definitions embedded in OpenAPI Swagger specs (they are probably not synced but supposed to I guess) ? Is it suggested to use one of these schema files as a base entity for creation of extended schema ?

    For example an extension of Recommendation entity schema could be :

    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$ref": "#/definitions/MyRecommendation",
      "title": "MyRecommendation",
      "description": "My extension of Recommendation Schema",
      "definitions": {
        "MyRecommendation": {
          "$id": "MyRecommendation",    
          "type": "object",
          "properties": {
            // My Custom properties go here
          },
          "allOf":[
              {
                 "$ref": "Recommendation.schema.json#Recommendation"      
              }
            ]
        }
      }
    }​

    An Organization's OpenAPI implementation could reference the above schema location in API response and also in Implementation Swagger specs (See https://swagger.io/docs/specification/using-ref/#syntax)

    	{"id": "1001",
    	"href": "http://serverlocation:port/recommendation/v1/recommendation/1001",
    	"name": "recommendationofthelatestAppleiPhone",
    	"description": " recommendation of the latest Apple iPhone for the customer with high revenue contribution",
    	"@type": "recommendation",
    	"@schemaLocation": "http://serverlocation:port/recommendation/schema/myrecommendation.schma.json",
    	"@baseType": "myrecommendation",
            "item":
              [{"priority": 1,
    	    "offering": {
    	    "href": "https://host:port/productOffering/v1/productOfferings/6547",
    	     "id": "6547",
    	     "name": "phone1"
    	}}],
            "type":"OFFER"
           }
    ​



    ​​​

    ------------------------------
    Indranil RoyChowdhury
    Ericsson Inc.
    ------------------------------



  • 4.  RE: TMF 680 API v4.0.0 API Specification and Conformance Profile

    TM Forum Member
    Posted Jan 16, 2020 09:45
    Hi Indranil

    This GitHub repository (tmforum-rand) is the area where the Open API team store our design work. The contents there are definitely not published, even if the schema folder happens to be public.

    We have moved to a schema-first mode of working, where the swagger files and spec documents for each API is generated directly from the schemas (and additional metadata) - so recently published APIs (from r18.5 and on) will have used common schema files so that the definitions are consistent across APIs. Note that the generation process flattens out include directives such as allOf, so in the swagger file the inheritance hierarchy will not be apparent. We try to ensure that the generated UML diagrams in the spec do show the inheritance hierarchy. Thus in Resource Catalog API (when it will be published - work-in-progress) you will see in the swagger LogicalResourceSpecification and PhysicalResourceSpecification as full class definitions, without it being apparent that they both inherit from ResourceSpecification. In the spec the diagrams will show the inheritance.

    It occurs to me that perhaps we should ask for a tooling update to preserve the inheritance in the swagger as well, I will see if I can get that discussed in the team.

    Your illustration above looks correct in general, but:
    • class names are full camel, so types start with capital letter, thus: MyRecommendation
    • you have reversed type and baseType, should be type=MyRecomendation, baseType=Recommendation
    Hope it helps


    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 5.  RE: TMF 680 API v4.0.0 API Specification and Conformance Profile

    TM Forum Member
    Posted Feb 13, 2020 11:50
    Edited by Indranil RoyChowdhury Feb 13, 2020 11:56
    @Jonathan Goldberg  ​thank you for taking time to review the examples. I have another question on the Response structure of TMF 680.Appreciate if you can help me here as  well.

    This is with respect to CategoryRef entity in the response of the API endpoint "/recommendation" - the specification document and swagger v2 indicates following attributes as part of entity in response..
    Q1. The schema https://github.com/tmforum-rand/schemas/blob/R19.0/Product/CategoryRef.schema.json however seems to have an additional property "version" in it.Shouldn't this be part of Swagger spec too ?

    Q2. I understand that the CategoryRef points to a Category object represented by the schema https://github.com/tmforum-rand/schemas/blob/R19.0/Product/Category.schema.json . However, the category schema seems to be more suited to grouping Product Offerings than represent Recommendation category (i.e. different flavors of recommendation)..Is it acceptable to use the Product/Category schema (from conformance stand point) to represent a Recommendation category ?

    ------------------------------
    Indranil RoyChowdhury
    Ericsson Inc.
    ------------------------------