feat(catalog): Add `Instance ID` below the service's `API ID`

[zFernand0]

Is your feature request related to a problem? Please describe.

It's a bit hard to get the available instance IDs for a particular service. User have to navigate to the API Gateway /services endpoint (which they may not have access to) in order to obtain a list of instances.

Describe the solution you'd like

To display the list of Instance IDs below the API ID (appid)

Describe alternatives you've considered

Continue with the current approach. Here are some steps:

1. Copy the API ID from the service
2. Go to API Gateway /services endpoint
   • Request access if you don't have it
3. Click Try it out and paste the copied API ID from step 1
4. Review the JSON output to get the instance IDs

Willingness to help

💯% willing to help 😋

Additional context

N/A

[balhar-jakub]

Thanks for sharing. This is linked to this Feature #3129. We intend to get to it in the 24PI2.

[dkelosky]

Currently obtaining the instance ID is done as described in #3254 . However, requesting services via /gateway/api/v1/services is SAF protected. We probably cannot add the instance ID to this UI since it is protected information. Similarly, we should consider removing the Instance URL from the UI.

The original justification / reasoning was given here: https://cwe.mitre.org/data/definitions/200.html And additionally here: https://cwe.mitre.org/data/definitions/497.html

We may need any scheme to return identifiers for each instance that do not also expose system or network information like host and port names.

[balhar-jakub]

If we don't need the info to be human readable, we can return hashes of the instance ids in unprotected way without exposing sensitive information.

[dkelosky]

From a technical standpoint, it seems like that might work. However the UX might be a little awkward. The idea would be instead of Instance URL we have Instance References(?) with a list of hashes representing each instance.

Perhaps we could have a query endpoint where the user could input a system / LPAR name and APIML could return a list of instance hashes that are running on that system?

@JirkaAichler @zFernand0 can you comment or perhaps iterate on this idea 😄 ?

[balhar-jakub]

This seems like an area where we need UX input, we can try reaching out to them.

[dkelosky]

X-InstanceId is the ideal/proper way to access an instance but presents a few UX challenges in practice:

• Most users at a site would not be able to easily determine what value to place on the “X-InstanceId” header because it is obtained via endpoint requiring READ access to APIML.SERVICES resource in the ZOWE class (SAF protected)
• If users have READ access, it is burdensome / non-obvious to obtain the instance identifier given that it’s an extra step a user needs to take (invoking another API request)
• The instance identifier is not user friendly, for example: STATIC-some.mainframe.host.net:someserviceid:8081 It contains the hostname and port of a service (which should be abstracted from the user)

Possible Solutions

• Display unique identifiers to represent the various instances within the API ML catalog UI e.g. serviceId +
  • Users would likely not be able to determine what actual instance is represented by the unique identifier
• Un-restrict the endpoints to view service instance information and display it in the UI (see GitHub Issues)
  • However, this is a security issue
• Provide instance identifier aliases for REST API services either manually or automatically (or both), e.g. serviceId+system_name
  • Users would likely know the system name or some site convention how to access a specific instance

For the last option, an end user (say zowe CLI user) could run zowe jobs list jobs --instance ibmzosmfsys1 or have the following in their team config:

  "type": "zosmf": {
  "properties": {
     "instance": "ibmzosmfsys1",
   ...

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[github-actions[bot]]

This issue has been automatically closed due to lack of activity. If you disagree, please comment on reason why and reopen the issue