Background
The Apigee Edge Module introduces a new RBAC security model. This model allows for more granular control of which API Products will appear on the New Application Creation and Edit Application screens (combined, these are shorthanded as the Edit Screen). The RBAC model allows for the visibility of API Products to be limited by Drupal Roles. In this way, it gives the Drupal site administrators more granular control over who can add API Products to their applications on the Edit Screen.
The initial conversation email around this subject solicited responses that indicated a desire to re-evaluate the current setup for API Product visibility and it’s documentation (Email subject line: Drupal RBAC Permissions, Sent: 2021-04-22 17:42 PST).
Purpose
The goal of this page is to help clarify the different aspect of API Product visibility points within the Drupal portal, the connection of those points to Apigee’s configuration, the API Gateway teams processes for implementation and configuration of the system.
Access vs RBAC Visibility
Access - Within the Edge Portal, when creating an API Product, you define an Access value from three options: Public, Private or Internal. Private and Internal are the exact same thing, Internal is a remnant from a previous version of the product.
Access based | RBAC based | |
|---|---|---|
Visibility Description |
|
 |
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. 
|
 |
Visibility Throughout the Developer Portal
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: /wiki/spaces/CWA/pages/1307902011. This is a reworking of those same notes for clarity:
= 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 |
|
|
|
Approval Required |
|
|
|
Private |
|
| Default is to list it |
Concerns Raised
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.
Definitions
API/API Products/API Endpoints - In this document these can be used interchangeably. There is a technical difference between them within Apigee, but we will predominantly talking about API Products.
Developer Portal/Drupal Site - The Drupal based site, https://developer.ucsb.edu (or, in this case, we will often be referring to the newer Drupal 8 version that is being developed, dev-developer-ucsb-edu-v05.pantheon.io)
Edit Screen - Used to represent both the New Application Screen and Edit Application Screen for Apigee applications. On these screens, a list of available API Products is shown to the end user, and they use check boxes to indicate which API they want their application to use.
Edge/Edge Portal/Edge Admin/Apigee Portal - This is the Cloud-based Apigee Edge Administrative Portal (https://apigee.com/edge).
Swagger Docs - These are the individual API Swagger documents that are primarily used by end users for (1) testing out endpoints before they do development work and (2) provide specs for the apis (which, in this case, have a 1-to-1 correlation with API Products).
End User/API Requestor/API Consumer - These are the people that sign up for accounts on the Developer Portal. They register and update applications through the Drupal portal, and they try out the APIs using the swagger docs.