Visibility Control

Overview

The Visibility Control API is a Helper service within OpenCAPIF that allows API Providers and administrators to define fine-grained rules that determine whether specific APIs can be discovered and consumed by API Invokers.

Based on this, the discovery process returns only the APIs that the Invoker is authorized to access. This approach restricts visibility from the very beginning, ensuring the Invoker cannot even see unauthorized AEFs during discovery.

Note: The first version of this API was merged with the staging branch (Release 4). The complete changes and evolution have been developed for Release 5.

Testing & Documentation References

• Robot Tests Location:
  /capif/tests/features/Helper/Visibility Control Api/visibility_control.robot
• Test Plan Documentation:
  Available in the Visibility Control test plan.

---

Core Operations

1. Rules Management (API Provider)

User Story:
As an API Provider, I want to define access control rules for my APIs, so that I can decide which API Invokers are allowed or denied to access.

Acceptance Criteria: * The Provider can create, update, list, and delete access rules[cite: 1]. * Each rule includes filters (providerSelector, invokerExceptions), an enabled field, and a validity period (startsAt, endsAt)[cite: 1]. * The field default_access defines the default behavior (ALLOW or DENY)[cite: 1]. * The Helper validates Provider identity, the rule structure, time, and consistency overall. * Only enabled and time-valid rules are enforced by the CCF.

Example: Rule Creation Request Payload

{
  "providerSelector": {
    "createdByUser": "userA",
    "apiProviderId": [ "capif-prov-01", "capif-prov-02" ],
    "apiName": [ "apiName-001" ],
    "apiId": [ "apiId-001" ],
    "aefId": [ "aef-001" ]
  },
  "invokerExceptions": {
    "apiInvokerId": [ "invk-123", "invk-999" ]
  },
  "default_access": "ALLOW",
  "enabled": true
}

Rules Creation Sequence Diagram

sequenceDiagram
    participant Provider as API Provider
    participant Helper as Helper
    participant DB as RulesDB

    Provider->> Helper: 1. POST /rules (rule body)
    Helper-->>Helper: 2. Verify Provider Identity
    Helper-->>Helper: 3. Data validation
    Helper-->>Helper: 4. Time validity (e.g. startsAt < endsAt)

    alt Rule invalid
        Helper-->>Provider: 400 Bad Request (validation errors)
    else Rule valid
        Helper->>DB: 5. Store rule in RulesDB
        DB-->>Helper: ruleId + timestamps
        Helper-->>Provider: 201 Created (ruleId + metadata)
    end

---

2. Access Decision (API Invoker)

User Story:
As an API Invoker, I want to discover APIs published by Providers, but I will discover only those that I am authorized to see according to the Provider/Admin’s rules.

Acceptance Criteria & Decision Workflow:
When sending a Service API Discovery Request, the CCF executes the following process:

1. Identity & Discovery Initiation:
2. Verifies the identity of the Invoker.
3. Lists all published APIs.
4. (Note: This first part is the current Discovery Process).
5. Decision Evaluation (POST /decision/invokers/{apiInvokerId}/discoverable-apis):[cite: 1]
6. Fetches the list of rules (GET /rules) and filters out inactive ones (retains rules where enabled=true and startsAt <= now < endsAt)[cite: 1].
7. Filters the active rules that belong to the specific apiInvokerId[cite: 1].
8. Matches those rules against all published APIs.
9. Selects the winnerRule for each API based on the granularity of each rule.
10. Enforcement:
11. Checks whether the Invoker is explicitly allowed or denied.
12. If allowed: The API is included in the discovery response.
13. If denied: The API is not listed (or a 403 Forbidden status is returned if invoked directly).
14. Response: Returns the final list of discoverable APIs[cite: 1].

Access Decision Sequence Diagram

sequenceDiagram
    actor Client as API Invoker
    participant Discovery as Discovery Service
    participant Visibility as Visibility Control
    participant DB as MongoDB

    Client->>Discovery: GET /discovered-apis
    Note over Discovery: Collect all published APIs

    Discovery->>Visibility: POST /decision/invokers/{id}/discoverable-apis
    Note over Discovery,Visibility: Send API list for filtering

    Visibility->>Visibility: Extract serviceAPIDescriptions
    Visibility->>DB: Get active visibility rules
    DB-->>Visibility: Rules list
    Visibility->>Visibility: Check active rules (enabled, expiration)

    Note over Visibility: For each API
    Visibility->>Visibility: Check rules matching
    Visibility->>Visibility: Check rules specificity
    Visibility->>Visibility: Apply ALLOW/DENY filter

    Visibility-->>Discovery: 200 OK + Filtered APIs

    Discovery->>Discovery: Update json_docs
    alt APIs found
        Discovery-->>Client: 200 OK + DiscoveredAPIs
    else No visible APIs
        Discovery-->>Client: 404 Not Found
    end

---

API Endpoints & Response Summary

Below is a summary of the available endpoints, HTTP methods, descriptions, and possible response codes based on the OpenAPI specification:

Endpoint	Method	Description	Output / Status Codes
/rules	GET	Retrieves a list of all defined visibility rules.	200 OK: JSON object containing an array of rules (items) and optional nextPageToken.
/rules	POST	Creates a new visibility rule (server generates ruleId).	201 Created: Returns created Rule object. 400 Bad Request: Invalid input/structure.
/rules/{ruleId}	GET	Retrieves details of a specific rule by ID.	200 OK: Rule object details. 404 Not Found: Rule does not exist.
/rules/{ruleId}	PATCH	Partially updates fields in an existing rule.	200 OK: Updated Rule object. 400 Bad Request: Invalid payload. 404 Not Found: Rule not found.
/rules/{ruleId}	DELETE	Removes a specific rule by ID.	204 No Content: Successfully deleted. 404 Not Found: Rule not found.
/decision/invokers/{apiInvokerId}/discoverable-apis	GET / POST	Evaluates and returns filtered discoverable APIs for the given invoker.	200 OK: DiscoveredAPIs list matching active rules. 400 Bad Request: Invalid parameters. 404 Not Found: Invoker not found.

---