Open APIs

 View Only

  • 1.  Usage of extension schema (TMF630) in spec design for API following TMF672

    Posted Oct 21, 2024 09:52
    Dear Members,
     
    We are designing a User Permission API as per the TMF 672 v5.0.0 spec and have some queries on the attributes like @type, @baseType etc and the applicable API URI endpoints.
     
    1. While POSTing a permissionSpecification resource, we have to add few attributes to the request which is not in TMF672 spec v5.0.0. As per guidelines in TMF630 (Chapter 1 and 2), can we extend the PermissionSpecification schema and introduce a new subtype e.g. "Permission", so the request would be as below:
     
    {
    "@type": "Permission",   -- this is the extended schema.
    "@baseType": "PermissionSpecification",
    "@schemaLocation": "/my-loc/api/permissionSpecificationWithStatus.yml",
    "id": "ps-7e0a2d18",
    "function": "Report",
    "action": "view",
    "name": "Permission for report",
    "status": "active"
    }
     
    2. Similarly to (1) above can the extension be applied to other resources like "PermissionSpecificationSet" and "PermissionSet"
     
     
    Please can someone help and provide any inputs for the above queries.
     
    Thanks,
    Satish


    ------------------------------
    Satish Kumar
    ------------------------------


  • 2.  RE: Usage of extension schema (TMF630) in spec design for API following TMF672

    Posted Oct 22, 2024 03:52
    Edited by Lutz Bettge Oct 22, 2024 03:52

    Dear Satish,

    first of all, as you are talking about V5, TMF630 is not the correct version of the guidelines; unfortunately, the V5 guidelines are still work in progress; as far as I know they are managed under the ID TMF763, and part 1 is on the way to be reviewed and published, the date depends on the processes progress. Reach out to Pierre Gauthier for the status/plans.

    Your structure and in particular the use of the @-attributes looks OK when talking about a V4 API; only if the example is from a POST, it must not contain the id of the to be created resource, the id is meant to be created by the service implementing the API and will only be returned in the response.

    Open APIs V5 are based on Open API Specification (OAS) 3.0, and they make heavily use of allOf/anyOf features, so your extension of PermissionSpecification in extension of the additional attributes and use of the @-attributes should use "allOf PermissionSpecification" to include all attributes of the base class.

    Also, the V5 APIs use the @type as discriminator, and thus must be required for all resources.

    Remark: Permission probably should not be a specialization/subclass of PermissionSpecification; a type of Permission is specified/described by a PermissionSpecification, but it is no PermissionSpecification ...

    And finally: V5 APIs are not "crafted by hand", but they are compiled by the V5 tooling from a so-called rules-file that amongst others refers to schemas (json schema files) of the contained resources. So creating a new V5 API or upgrading an existing API to V5 should be done by creating/modifying the rules file and the referred schema files.

    The structure of the schema files is described in Part 7 of the guidelines, with - sorry - the V5 version still work in progress.



    ------------------------------
    Lutz Bettge
    Deutsche Telekom AG
    ------------------------------



  • 3.  RE: Usage of extension schema (TMF630) in spec design for API following TMF672

    Posted Oct 22, 2024 04:00

    Hi Satish

    Sub-classing the Permission[Set]Specification for a Permission[Set] instance will break the entitySpec/entity pattern.  Rather than adding your extended status field, it may be better to add the entitySpecification lifecycleStatus and version fields to the Permission[Set]Specification.  I can raise a JIRA ticket on this in TM Forum and you can temporarily add these fields to your version of the TMF672 OAS.

    Note that there have been considerable changes between the TMF672 v4 and v5 APIs.  Permission in v4 has been replaced with a PermissionSet instead.  The permissions within the PermissionSet are embedded permissions.

    Otherwise, in terms of your polymorphism fields, these are generally correct except perhaps you could use something like @type=PermissionSetSpecificationExtension (rather than PermissionSet the entity/instance).



    ------------------------------
    Dan d'Albuquerque
    Individual
    ------------------------------



  • 4.  RE: Usage of extension schema (TMF630) in spec design for API following TMF672

    Posted Oct 23, 2024 00:07

    Thanks Lutz and Dan for your response.

    In v5 spec, for a permissionSet resource, I see the payload / spec has these two fields in request:
    > permission. (permission also has a permissionSpecificationSet)

    > permissionSetSpecification

    So what is the difference between "permissionSpecificationSet" inside "permission" field and the "permissionSetSpecification". The reference class for both of them is same- "PermissionSpecificationSetRef".

    Thanks,

    Satish



    ------------------------------
    Satish Kumar
    Telstra Corporation
    ------------------------------

    Original Message


  • 5.  RE: Usage of extension schema (TMF630) in spec design for API following TMF672

    Posted Oct 24, 2024 22:42

    Hi Satish

    The permissionSetSpecification tied to the permissionSet resource is for the implicit permissions automatically assigned to the party playing a PartyRole.  When the PartyRole is instatiated for the Party, a PermissionSet (implicit) should be created at the same time, based on the association between the PartyRoleSpecification and the PermissionSpecificationSet.

    The permission field within PermissionSet is for assigning a permission or permissions (set) relating to specific managed entities, e.g. a specific Product.

    Jonathan Goldberg wrote a summary of this API on the TM Forum wiki at TMF672 User Role Permission API V5.0.0 - Open API Project - TM Forum Confluence

    Hope this helps



    ------------------------------
    Dan d'Albuquerque
    Individual
    ------------------------------

    Original Message


  • 6.  RE: Usage of extension schema (TMF630) in spec design for API following TMF672

    Posted Nov 03, 2024 05:07

    Thanks Dan for clarifying the above.

    TMF672 also has notification event endpoints. But currently our specific implementation doesnt require any notifications to be sent.

    So, Is it also mandatory to implement those endpoints when following TMF672 spec?



    ------------------------------
    Satish Kumar
    Telstra Corporation
    ------------------------------

    Original Message


  • 7.  RE: Usage of extension schema (TMF630) in spec design for API following TMF672

    Posted Nov 03, 2024 20:30

    No, currently there are no mandatory notifications on the TMF672 Roles and Permissions API.




    Original Message


Related Content