Open APIs

 View Only

  • 1.  API development

    TM Forum Member
    Posted Apr 17, 2017 15:12
    If we create an API today in one place - it will be different in another place, and definitely different a year from now. How will the open API's follow the development of the services they are connecting to?

    ------------------------------
    Kaj Jonasson
    Applied BSS
    ------------------------------


  • 2.  RE: API development

    TM Forum Member
    Posted Jun 07, 2017 12:26
    Hi Kai
    the APIs created and crowd sourced inside the Forum are intended to be service agnostic.  we are also committing to no more than 2 major updates in any one year. 

    we have created a governance process published in fx 16.5 and there will be further enhancements to the Fx 17 version. 

    you can view the latest published version here:
    GB996 API Governance Practice R16.5.1 - TM Forum

    thanks

    ------------------------------
    Joann O'Brien
    TM Forum
    ------------------------------

    Original Message


  • 3.  RE: API development

    Posted Oct 11, 2017 19:56
    My personal recommendation would be to hide the TMF Open APIs behind a more consumer focused set of experience APIs. I'm pretty concerned about the idea that major releases could come twice per year - is that going to include version updates? That a very high rate of change for underlying APIs which are already heavyweight...

    Also, there are some gaps in the way the current APIs are modeled. Trying to shoe-horn in SID like resource constructs has led to some significant bloat and burden of understanding. At the moment the APIs are very bottom up and therefore not fit for direct use by channels. 

    You need to provide a layer of tailored abstraction which insulates the client from underlying changes and also provides a more consumer focused experience. 

    IMHO

    ------------------------------
    Craig Bayley
    MuleSoft
    ------------------------------

    Original Message


  • 4.  RE: API development

    TM Forum Member
    Posted Jan 23, 2018 11:11
    Hi,

    My points in reply:
    • "to hide the TMF Open APIs behind a more consumer focused set of experience APIs"
      Yes, I agree to the idea of consumer-focused APIs. I think it was Gartner that first proposed the bi-model, or pace-layered-architecture view of telco - separating "Systems of Experience" (web portals, mobile-apps etc) from "Systems of Record" (CRM, Billing, Fulfillment, Assurance etc). The latter is characterized by highly process-based, heavily regulated interactions (SOx, PCI, GDPR, DPA) with more traditional, monolithic systems while the former is characterized by agile, sprint-based development, CI/CD processes, A-B testing etc.
      Imagine a holographic avatar engaging you in a conversation about your mobile use (natural-language processing, AI/ML algorithms, holograms, 3D-modelling...) - this is the land of consumer-focused, channel-specific, use-case driven agile software. At the end of this you've figured out a recommended purchase and the Avatar asks you if you want to buy it. You say/click/gesture "yes" - and that invokes the TMF Open-API for Create.ProductOrder(ProductOffering[]) - and off into the highly regulated/process-oriented world of purchase and fulfillment.
    • "concerned about the idea that major releases could come twice per year"
      That is only to say that the API programme works to two 'significant' (to avoid the over-loaded term: major) release cycles in a year. It is not to say that we aim to make a major (breaking change) to any API. All API work is demand driven. They only change when there is new demand to do so, and we try very hard not to break them through backwards incompatibility. Some APIs have been untouched since 2014.
    • "Trying to shoe-horn in SID like resource constructs has led to some significant bloat and burden of understanding"
      While I don't disagree, I would say:
      • Each TMF Open-API has its own API data model. This is derived from relevant SID entities but does not make use of all attributes/relationships if not relevant to the API interaction. SID is only the conceptual data-model in this sense.
      • "burden of understanding": Yes - but the underlying business is complex :-). Picking ProductOfferings from a ProductCatalog, each of which may carry discounts, be paid for through vouchers and other payment methods - either one-off or subscription etc. While the APIs purpose is to abstract this complexity, you can only go so far. A "bloat" eludes to "unnecessary" - and I haven't yet seen an attribute or relationship built into an API that is unnecessary to everyone.
    • "need to provide a layer of tailored abstraction which insulates the client from underlying changes"
      There is a need for both, but I would start with the systems-of-reference, abstracting high-level domains like parties (suppliers/partners/customers: consumer, enterprise, SME/SOHO/Corporate/Multi-National), products (offerings in a catalog that could come from fixed, mobile, TV, broadband or fridges) etc - and that is where the TMF Open-APIs are focused. This gives a stable abstraction for the systems-of-experience to build on.


    ------------------------------
    Stephen Harrop
    Principal Integration Architect
    Vodafone Group
    ------------------------------

    Original Message


  • 5.  RE: API development

    Posted 29 days ago
    You're right that APIs often evolve over time, and keeping them aligned with the services they connect to can be a challenge. Open APIs (like RESTful APIs, GraphQL, or gRPC) face the same issues, but there are a few strategies that help manage API evolution and ensure consistency across versions:
     
    Versioning: One of the most common strategies is versioning the API. This allows you to introduce breaking changes without affecting existing consumers. APIs can be versioned in the URL (e.g., /api/v1/) or in the headers, which allows developers to continue using the old version of the API while new consumers can adopt newer versions.
     
    Deprecation Strategies: When new features are added or changes are made, older versions of an API might be deprecated. A good deprecation strategy involves clear communication (via documentation, email, etc.) and providing a migration path for consumers to transition to newer versions. This can be particularly useful for Open APIs, where users might be integrating with various platforms and services.
     
    Backward Compatibility: Whenever possible, try to maintain backward compatibility, especially for major, widely-used services. Adding new optional fields or endpoints without breaking existing functionality can ensure that older clients continue to work even as the API evolves.
     
    OpenAPI Specification (formerly Swagger): The OpenAPI Specification is an industry-standard format for describing APIs. It helps create a contract between the API provider and consumers. This contract can be used to auto-generate client libraries, documentation, and tests, making it easier to ensure that API changes are understood and compatible with the service consumers.
     
    Continuous Integration and Testing: To ensure that changes don't break existing functionality, automated testing, such as contract testing, can be employed. Tools like Pact allow teams to test and ensure that different parts of the system are still communicating as expected, even as APIs evolve.
     
    API Gateways and Middleware: Using an API gateway or middleware layer can help manage differences in API versions across various services. The gateway can route requests to the correct version of the backend service, even if the API changes over time.
     
    Semantic Versioning: This system uses three numbers (major.minor.patch) to indicate changes in an API. For example:
     
    Major version changes (e.g., 1.x → 2.0) imply backward-incompatible changes.
    Minor version changes (e.g., 1.1 → 1.2) introduce new features but maintain backward compatibility.
    Patch version changes (e.g., 1.1.1 → 1.1.2) are for bug fixes and minor improvements.
    Community Feedback and Documentation: Open APIs often involve external developers, so it's crucial to have detailed, up-to-date documentation and a way for the community to provide feedback on issues or unexpected changes. This could involve a changelog and an FAQ or troubleshooting section that highlights known problems.


    ------------------------------
    Ronald Higgins
    TO BE VERIFIED
    ------------------------------

    Original Message