Open APIs

 View Only

  • 1.  Implementation Advice > Versioning, @Type Specifications, Lifecycle Management

    Posted Apr 09, 2024 08:09
    Edited by Ilyas Premji Apr 09, 2024 09:11

    Hi,

    in regards to planning of an implementation project (which may be e.g. TMF645), can you please share your insights and best practices in regards to the following questions?

    a) the version information for an API implementation does not seem to be recommended as part of the URI, so did you choose to specify the version in the header?

    b) the @type model seems to be proprietary on top of the OpenAPI specification, and which approach did you choose to specification which types are actually understood by the API? Eg. TMF645 talks about Place @types, so it could be an adress, geo coordinates, what3words, some internal id or whatever => how did you specify that for each of the API implementation versions, and did you enrich the TMF api with an additional proprietary endpoint to query about what is supported, or how did you approach that?

    c) the APIs are generally pretty large and detailed, so in multiple iterations we don't plan to implement in a "big bang" approach, but to iteratively add more endpoints as needed, so did you find a good tool to specify which endpoints you decided for each implementation version, and which of the many parameters to support? we would like to avoid to having to modify the openAPI specification (like to remove endpoints or so) - is there any supportive system for that? then to follow a contract-first approach for implementation

    Thanks a lot

    Marco



    ------------------------------
    Marco Nissen
    Lyse Tele AS
    ------------------------------



  • 2.  RE: Implementation Advice > Versioning, @Type Specifications, Lifecycle Management

    Posted Apr 11, 2024 01:33

    Hi Marco

    One small amendment - the recommended uri for API endpoints does include the major version (e.g. productCatalogManagement/v5/productspecification)

    We mandate the semver versioning semantics for APIs, where a major version implies a backward compatibility breaking change, while a minor version preserves backward compatibility. So an implementation that wants to support multiple versions will typically expose two (or more) endpoints, one for each major version. However minor versions (and patches) are not represented in the endpoint, since consumers don't get to say which minor version they want. The consumer should not be affected by a minor version change (otherwise it's not a minor version change ...).

    I will add that we expect consumers to be resilient - for example if a new output property was added in a minor version (which is generally not a breaking change) the consumer should be able to ignore the extra property that is received in the output.



    ------------------------------
    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: Implementation Advice > Versioning, @Type Specifications, Lifecycle Management

    Posted Apr 11, 2024 02:07

    Hi Jonathan

    thanks so much. Also I found already TMF630 which goes into detail about the versioning usage. Yes, semantic version is known and used. Thanks

    For the other practical questions, do you also have some best practices (note there are many possibilities to approach the lifecycle) in regards to the TMF specs?

    Thanks

    Marco



    ------------------------------
    Marco Nissen
    Lyse Tele AS
    ------------------------------

    Original Message


Related Content