Open APIs

Expand all | Collapse all

Suggest improvements to the Open API table - what would make it easier to use?

  • 1.  Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 12, 2021 08:29
    We are looking at how we can improve the Open API table and it's contents and would be interested in what would help you view and use them.

    • Can you always find what you are looking for?
    • Is all the information you need there?
    • Is it laid out in an easy-to-use way?

    Please let us know either way, is it perfect as it is or could you suggest some improvements?

    We have had a session with the Open API team and are particularly looking for input from users of the API's and table.

    ------------------------------
    Sue Davis
    Head of Product Design
    TM Forum
    ------------------------------


  • 2.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 12, 2021 11:28
    Hi Sue
    Great idea, hope you get lots of feedback from the users.
    One small point - it would be a great idea to add a link to the current design guidelines TMF630. I often find that I need to refer people to these guidelines when I am replying to queries on Open APIs, so giving them more visibility would certainly help.
    Hope this is useful feedback.

    ------------------------------
    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: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 12, 2021 13:07
    Perfect Jonathan, it's exactly this sort of feedback we are looking for.

    Thank you

    ------------------------------
    Sue Davis
    Head of Product Design
    TM Forum
    ------------------------------



  • 4.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 12, 2021 17:31
    Hi Sue, I agree with Jonathan, and I believe that the Design Guidelines should be available to non-members; else, they only have half of the story!

    Here are other areas which could be improved:
    -  First, when we get to the Open API table main page - could we have a login prominently displayed along with a register button since you can't download anything without logging in? It would be good to mention these are Open Sourced API but still requires registration before download. People think you need to be a member if you need to log in.
    -  When you get to the page, there is a lot of text above the table(s) - could that be reduced or links provided to review the text, so people get to Open API Table faster?
    -  Should the title of the main table also reflect that it's not just a container with several tables below but, in fact, the main and current Open API table?
    -  This relates to the previous comment as if you don't know where the current table is, the BETA table as the first entry is confusing vs. the historic and N-2 tables
    - and what is the difference between historic and N-2?? Could an explanation be provided beside the title or when you hover over the title?

    Hopefully, this is the type of thing you were looking for!

    ------------------------------
    Johanne Mayer
    MayerConsult Inc
    ------------------------------



  • 5.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 05:12
    Perfect thanks Johanne

    ------------------------------
    Sue Davis
    Head of Product Design
    TM Forum
    ------------------------------



  • 6.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 14, 2021 05:32
    Hi Johanne,
    • If someone opens the page when they are not logged in, they get the following message:


    • I have reduced the amount of text at the top of the page and added a link to TMF630 API Design Guidelines
    • I have changed the title of the page to Open API Table - Production to reflect the status of the content
    • The Historic table was set up so that the main table would only list current/complete APIs.
      • We will review the N-2 content and either add these to the Historic table or remove them.


    ------------------------------
    Alan Pope
    Collaboration Manager
    TM Forum
    United Kingdom
    ------------------------------



  • 7.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 14, 2021 09:06
    Thank you Alan! That is great service!

    ------------------------------
    Johanne Mayer
    MayerConsult Inc
    ------------------------------



  • 8.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 12, 2021 21:01
    Hi Sue,

    A great initiative.

    My feedback would be

    1. A button at the top to filter domain-specific APIs like if I want to search Customer (or Common or Service) domain APIs.
    2. A message/link against an API, if in case a pre-production version is available. Right now, we have to search at 2 places. This is similar lines to what we have for our resources where we get a "Heads up!" pop-up in case we look for an old version of the document. the pop-up indicates and provides a link to the current version.


    ------------------------------
    Abdul Majid Hussain
    Telstra Corporation
    ------------------------------



  • 9.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 05:14
    Thanks Abdul, we are planning to bring it all to one place. Appreciate the suggestions.

    ------------------------------
    Sue Davis
    Head of Product Design
    TM Forum
    ------------------------------



  • 10.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 10:13
    I second both of Abdul's suggestions, those will be big wins for usability. Glad to hear the tables will be rolled together.

    As part of brining it all to one place - would a link to this discussion forum, filtered by the API number, be useful? Understood discussions don't always include the reference number, but it could be a good reminder to check for recent activity here too if people have questions.

    Take care,
    Karen

    ------------------------------
    Karen Aiken
    TELUS
    ------------------------------



  • 11.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 12:24
    Thanks for the input Karen. We are moving the Community to a new platform as well so it's a good time to think about linking these together.


    ------------------------------
    Sue Davis
    Head of Product Design
    TM Forum
    ------------------------------



  • 12.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 03:43
    Great initiative - many thanks for taking input from us users (even us infrequent users!)

    One comment I have is that it's really difficult to share a link to a *specific* API specification (whether in PDF or openAPI format), because all the links in the table just start javascript functions to download. Currently I have to either (a) download the spec and share that; (b) share a link to the whole openAPI table; or (c) dig into the page source to work out what the link might be...

    ------------------------------
    Stephen Connor
    Cortex
    ------------------------------



  • 13.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 05:16
    Thanks Stephen, got it. I'll add that in.

    ------------------------------
    Sue Davis
    Head of Product Design
    TM Forum
    ------------------------------



  • 14.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 05:50
    Hey Sue thanks for reaching out on this.

    First i'd echo @Johanne Mayer's comments about the historic and N-2 as i dont understand the difference. The other thing i'd mention is that there are some TMF numbers which appear in these tables which dont exists in the latest table, does this mean they are depricated and should not be used? For example "TMF673 Geographic address management" is in the historic table, i would assume it isnt used but then wonder what should be used instead, perhaps the historic/archive needs an extra column to point to an alternative or suggest that the concept/entities that the API models are depricated.

    The other thing which could be good is links like this (https://www.tmforum.org/resources/specification/tmf666-account-management-api-rest-specification-r19-0-0/) currently dont contain a link back to the open api table to explore the rest of the API's and vise versa the name of the API in the open api table isnt a link to the page talking about that API. I used google a lot in the first instance to explore the API's and its the above type of link that it shows as a top hit.



    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 15.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 06:39
    Hi David
    Specifically regarding the APIs that have "disappeared" - as far as I understand, the management decided that APIs beyond a certain age should be "relegated" to the historical table https://projects.tmforum.org/wiki/display/API/Open+API+Table+-+Historic
    Some of them are being re-worked to align with V4 and have been published as draft in the early adoption page https://projects.tmforum.org/wiki/pages/viewpage.action?pageId=128855518 - others are still in progress.
    Regarding your suggestion to embed a permanent link within the user guide to the table, that's an interesting thought and could be raised to the Open API tooling team for possible implementation as we move to V5 of the APIs.

    ------------------------------
    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.
    ------------------------------



  • 16.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 13, 2021 12:27
    Edited by Sue Davis Jul 13, 2021 12:28
    Thanks David. Jonathan has responded above and I'll feed the rest into the project.

    ------------------------------
    Sue Davis
    Head of Product Design
    TM Forum
    ------------------------------



  • 17.  RE: Suggest improvements to the Open API table - what would make it easier to use?

    TM Forum Member
    Posted Jul 14, 2021 09:13
    Hi Sue,

    it seems like the table does not contain links to the most recent publications of the user guides.

    For example: "TMF666 Account Management API REST Specification" (this also appplies to other documents)
    Version 19.0.1 is available for download at https://www.tmforum.org/resources/specification/tmf666-account-management-api-rest-specification-r19-0-0/
    Version 19.0.0 is available for download in the Open API table.

    It would be great, if the Open API table is kept up to date with the most recent versions of all documents.

    Thank you

    ------------------------------
    Markus Sauermann
    Universitat der Bundeswehr
    ------------------------------