Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Access based

RBAC based

Visibility Description

  • The Edit Screen only shows API Products with Access set to Public.

    Image RemovedImage Added

  • The Edit Screen Ignores the Access setting.

Image RemovedImage Added

How does it handle an API Product being visible on the Edit Screen?

When an API Product is set to Access-Public, it is visible on the Edit Screen.

  • We currently ask that API Products which are expected to only be used by a select group of consumers be given a display name suffixed with “(Private)” and the description should be prefixed with “(Private, Access Approval Required)” (developer portal docs).

    • This allows for the API Products to be seen and requested by the application owner.

  • The Edit Screen shows the API Products selected as visible through the RBAC API product access screen.

Image RemovedImage Added

Preferred Option (will implement this)

...

On the API Gateway Team talked through Visibility of API brought up Jason La and Farah Tahmasbi (both Student Affairs developers; Jason works on Seth’s team); the slim notes from that conversation are here: .

We picked up the conversation and recorded notes on the original page, the new notes are in the section on:

...

 (tick) = The API Gateway teams wants the information to be visible to all

...

API Gateway Team Access Type

...

Swagger Docs

...

API Publishing Request List

...

Edit Screen

...

Public

...

(tick)

...

(tick)

...

(tick)

...

Approval Required

...

(tick)

...

(tick)

...

(tick)

...

Private

...

(tick)

...

(tick)

...

Default is to list it (tick), but … Publishers Choice

 

...

Concerns Raised

  • We did not use these notes as part of the conversation, please see the section of /wiki/spaces/CWA/pages/1307902011 for the real notes.

  • If an endpoint is private, should it even be listed on Edit Screen? Why not have applications added to those API Products by hand within Edge?

    • Reason for the Current Process:

      • If the application owner is the one requesting access to the API Product, it is in “better alignment” with compliance.

      • It puts the onus on the application owner to initiate the request process.

      • We currently have Public API Products which require Access Approval. And, we have a workflow for doing that. By reusing that same process for the Private endpoints, it’s less cognitive overhead to remember what to do; which ensures a more repeatable process.

      • The API Gateway team has strived to use the Swagger Docs to provide documentation and visibility into what API endpoints are available. By using Access-Public, we ensure that the Swagger Docs and Edit Screen match up; which lowers end user confusion.

    • Reasons against the Current Process:

      • The current process doesn’t completely line up with needs for Private endpoints. It’s a bit of putting a square peg into a round hole.

      • Is it really a tremendous amount of effort to log into the Edge Portal and add an application to an API Product by hand?

        • Background: I believe the initial thought on this was to use @apibot to do all the approvals, so that (1) we could have better visibility and auditability and (2) lower the number of licenses required in order to effective administrate the system.

          • Over the past 3 years: I think @apibot has:

            • Provided better visibility.

            • Auditability has been somewhat helped; but it hasn’t turned out to be a real value gain. Auditability has been improved by copying the slack link into the API Access Request’s workflow audit log. The API Access Request’s workflow audit log has been the real provider of auditability; and the slack link makes it easier to track the history.

            • Not always been easy to use. There’s a learning curve to use it and things can go wrong; it doesn’t work exactly as you expect every time. This lowers it’s adoption rate.

            • We haven’t really ran into a shortage of licenses for approvals. We’ve always found a workable solution.

        • It’s only takes a few minutes to log into the portal and setup and application.

      • If we move to Access-Private API Products and remove the listing of these APIs from the Edit Screen, and remove the associate Swagger Docs for these APIs; there wouldn’t be any change of end user confusion. But, in these situations, how do we provide (1) a test endpoint and (2) specs for the API endpoint to the end user?

        • Steven - I feel strongly that the documentation/specs need to be available in a standardized location and on a service that is available 24 hours a day (like the Swagger Docs on the Developer Portal). Sending specs to the consumer through email is too prone to getting lost, having multiple versions stored in multiple locations, and removes accountability on the API Provider to provide clear and consistent documentation.

...