Open APIs

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

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

Perfect Jonathan, it's exactly this sort of feedback we are looking for.

Thank you

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

Original Message:
Sent: Jul 12, 2021 11:28
From: Jonathan Goldberg
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

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

Perfect thanks Johanne

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

Original Message:
Sent: Jul 12, 2021 17:30
From: Johanne Mayer
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

Hi Johanne,

• If someone opens the page when they are not logged in, they get the following message:

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

Original Message:
Sent: Jul 12, 2021 17:30
From: Johanne Mayer
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

Thank you Alan! That is great service!

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

Original Message:
Sent: Jul 14, 2021 05:31
From: Alan Pope
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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


Original Message:
Sent: Jul 12, 2021 17:30
From: Johanne Mayer
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

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

Thanks Abdul, we are planning to bring it all to one place. Appreciate the suggestions.

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

Original Message:
Sent: Jul 12, 2021 21:01
From: Abdul Majid Hussain
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

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

Original Message:
Sent: Jul 13, 2021 05:14
From: Sue Davis
Subject: Suggest improvements to the Open API table - what would make it easier to use?

Thanks Abdul, we are planning to bring it all to one place. Appreciate the suggestions.

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


Original Message:
Sent: Jul 12, 2021 21:01
From: Abdul Majid Hussain
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

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

Original Message:
Sent: Jul 13, 2021 10:13
From: Karen Aiken
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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


Original Message:
Sent: Jul 13, 2021 05:14
From: Sue Davis
Subject: Suggest improvements to the Open API table - what would make it easier to use?

Thanks Abdul, we are planning to bring it all to one place. Appreciate the suggestions.

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


Original Message:
Sent: Jul 12, 2021 21:01
From: Abdul Majid Hussain
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

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

Thanks Stephen, got it. I'll add that in.

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

Original Message:
Sent: Jul 13, 2021 03:43
From: Stephen Connor
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

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

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

Original Message:
Sent: Jul 13, 2021 05:50
From: David Whitfield
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

Thanks David. Jonathan has responded above and I'll feed the rest into the project.

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

Original Message:
Sent: Jul 13, 2021 05:50
From: David Whitfield
Subject: Suggest improvements to the Open API table - what would make it easier to use?

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

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