Deployed 9fba778 to develop in public with MkDocs 1.6.1 and mike 2.2.0 (fa926cca) · Commits · OCF / documentation

public/develop/features/visibility-control/visibility-control/index.html

+442 −1

Original line number	Diff line number	Diff line
		@@ -1103,6 +1103,24 @@



		<label class="md-nav__link md-nav__link--active" for="__toc">



		<span class="md-ellipsis">


		Visibility Control



		</span>



		<span class="md-nav__icon md-icon"></span>
		</label>

		<a href="./" class="md-nav__link md-nav__link--active">


		@@ -1120,6 +1138,142 @@

		</a>



		<nav class="md-nav md-nav--secondary" aria-label="Table of contents">






		<label class="md-nav__title" for="__toc">
		<span class="md-nav__icon md-icon"></span>
		Table of contents
		</label>
		<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

		<li class="md-nav__item">
		<a href="#overview" class="md-nav__link">
		<span class="md-ellipsis">

		Overview

		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#testing-documentation-references" class="md-nav__link">
		<span class="md-ellipsis">

		Testing & Documentation References

		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#core-operations" class="md-nav__link">
		<span class="md-ellipsis">

		Core Operations

		</span>
		</a>

		<nav class="md-nav" aria-label="Core Operations">
		<ul class="md-nav__list">

		<li class="md-nav__item">
		<a href="#1-rules-management-api-provider" class="md-nav__link">
		<span class="md-ellipsis">

		1. Rules Management (API Provider)

		</span>
		</a>

		<nav class="md-nav" aria-label="1. Rules Management (API Provider)">
		<ul class="md-nav__list">

		<li class="md-nav__item">
		<a href="#example-rule-creation-request-payload" class="md-nav__link">
		<span class="md-ellipsis">

		Example: Rule Creation Request Payload

		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#rules-creation-sequence-diagram" class="md-nav__link">
		<span class="md-ellipsis">

		Rules Creation Sequence Diagram

		</span>
		</a>

		</li>

		</ul>
		</nav>

		</li>

		<li class="md-nav__item">
		<a href="#2-access-decision-api-invoker" class="md-nav__link">
		<span class="md-ellipsis">

		2. Access Decision (API Invoker)

		</span>
		</a>

		<nav class="md-nav" aria-label="2. Access Decision (API Invoker)">
		<ul class="md-nav__list">

		<li class="md-nav__item">
		<a href="#access-decision-sequence-diagram" class="md-nav__link">
		<span class="md-ellipsis">

		Access Decision Sequence Diagram

		</span>
		</a>

		</li>

		</ul>
		</nav>

		</li>

		</ul>
		</nav>

		</li>

		<li class="md-nav__item">
		<a href="#api-endpoints-response-summary" class="md-nav__link">
		<span class="md-ellipsis">

		API Endpoints & Response Summary

		</span>
		</a>

		</li>

		</ul>

		</nav>

		</li>


		@@ -1869,6 +2023,131 @@



		<label class="md-nav__title" for="__toc">
		<span class="md-nav__icon md-icon"></span>
		Table of contents
		</label>
		<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

		<li class="md-nav__item">
		<a href="#overview" class="md-nav__link">
		<span class="md-ellipsis">

		Overview

		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#testing-documentation-references" class="md-nav__link">
		<span class="md-ellipsis">

		Testing & Documentation References

		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#core-operations" class="md-nav__link">
		<span class="md-ellipsis">

		Core Operations

		</span>
		</a>

		<nav class="md-nav" aria-label="Core Operations">
		<ul class="md-nav__list">

		<li class="md-nav__item">
		<a href="#1-rules-management-api-provider" class="md-nav__link">
		<span class="md-ellipsis">

		1. Rules Management (API Provider)

		</span>
		</a>

		<nav class="md-nav" aria-label="1. Rules Management (API Provider)">
		<ul class="md-nav__list">

		<li class="md-nav__item">
		<a href="#example-rule-creation-request-payload" class="md-nav__link">
		<span class="md-ellipsis">

		Example: Rule Creation Request Payload

		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#rules-creation-sequence-diagram" class="md-nav__link">
		<span class="md-ellipsis">

		Rules Creation Sequence Diagram

		</span>
		</a>

		</li>

		</ul>
		</nav>

		</li>

		<li class="md-nav__item">
		<a href="#2-access-decision-api-invoker" class="md-nav__link">
		<span class="md-ellipsis">

		2. Access Decision (API Invoker)

		</span>
		</a>

		<nav class="md-nav" aria-label="2. Access Decision (API Invoker)">
		<ul class="md-nav__list">

		<li class="md-nav__item">
		<a href="#access-decision-sequence-diagram" class="md-nav__link">
		<span class="md-ellipsis">

		Access Decision Sequence Diagram

		</span>
		</a>

		</li>

		</ul>
		</nav>

		</li>

		</ul>
		</nav>

		</li>

		<li class="md-nav__item">
		<a href="#api-endpoints-response-summary" class="md-nav__link">
		<span class="md-ellipsis">

		API Endpoints & Response Summary

		</span>
		</a>

		</li>

		</ul>

		</nav>
		</div>
		</div>
		@@ -1891,7 +2170,169 @@


		<h1 id="visibility-control">Visibility Control</h1>
		<p>WORK IN PROGRESS</p>
		<h2 id="overview">Overview</h2>
		<p>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.</p>
		<p>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.</p>
		<p><em>Note: The first version of this API was merged with the staging branch (Release 4). The complete changes and evolution have been developed for </em><em>Release 5</em><em>.</em></p>
		<h2 id="testing-documentation-references">Testing & Documentation References</h2>
		<ul>
		<li><strong>Robot Tests Location:</strong><br />
		<code>/capif/tests/features/Helper/Visibility Control Api/visibility_control.robot</code></li>
		<li><strong>Test Plan Documentation:</strong><br />
		Available in the <a href="../../../testing/testplan/helper/visibility_control/">Visibility Control test plan</a>.</li>
		</ul>
		<hr />
		<h2 id="core-operations">Core Operations</h2>
		<h3 id="1-rules-management-api-provider">1. Rules Management (API Provider)</h3>
		<p><strong>User Story:</strong><br />
		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.</p>
		<p><strong>Acceptance Criteria:</strong>
		* The Provider can create, update, list, and delete access rules[cite: 1].
		* Each rule includes filters (<code>providerSelector</code>, <code>invokerExceptions</code>), an <code>enabled</code> field, and a validity period (<code>startsAt</code>, <code>endsAt</code>)[cite: 1].
		* The field <code>default_access</code> defines the default behavior (<code>ALLOW</code> or <code>DENY</code>)[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.</p>
		<h4 id="example-rule-creation-request-payload">Example: Rule Creation Request Payload</h4>
		<pre><code class="language-json">{
		"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
		}
		</code></pre>
		<h4 id="rules-creation-sequence-diagram">Rules Creation Sequence Diagram</h4>
		<pre><code class="language-mermaid">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
		</code></pre>
		<hr />
		<h3 id="2-access-decision-api-invoker">2. Access Decision (API Invoker)</h3>
		<p><strong>User Story:</strong><br />
		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.</p>
		<p><strong>Acceptance Criteria & Decision Workflow:</strong><br />
		When sending a Service API Discovery Request, the CCF executes the following process:</p>
		<ol>
		<li><strong>Identity & Discovery Initiation:</strong></li>
		<li>Verifies the identity of the Invoker.</li>
		<li>Lists all published APIs.</li>
		<li><em>(Note: This first part is the current Discovery Process).</em></li>
		<li><strong>Decision Evaluation (<code>POST /decision/invokers/{apiInvokerId}/discoverable-apis</code>):</strong>[cite: 1]</li>
		<li>Fetches the list of rules (<code>GET /rules</code>) and filters out inactive ones (retains rules where <code>enabled=true</code> and <code>startsAt <= now < endsAt</code>)[cite: 1].</li>
		<li>Filters the active rules that belong to the specific <code>apiInvokerId</code>[cite: 1].</li>
		<li>Matches those rules against all published APIs.</li>
		<li>Selects the <code>winnerRule</code> for each API based on the granularity of each rule.</li>
		<li><strong>Enforcement:</strong></li>
		<li>Checks whether the Invoker is explicitly allowed or denied.</li>
		<li><strong>If allowed:</strong> The API is included in the discovery response.</li>
		<li><strong>If denied:</strong> The API is not listed (or a <code>403 Forbidden</code> status is returned if invoked directly).</li>
		<li><strong>Response:</strong> Returns the final list of discoverable APIs[cite: 1].</li>
		</ol>
		<h4 id="access-decision-sequence-diagram">Access Decision Sequence Diagram</h4>
		<pre><code class="language-mermaid">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
		</code></pre>
		<hr />
		<h2 id="api-endpoints-response-summary">API Endpoints & Response Summary</h2>
		<p>Below is a summary of the available endpoints, HTTP methods, descriptions, and possible response codes based on the OpenAPI specification:</p>
		<table>
		<thead>
		<tr>
		<th style="text-align: left;">Endpoint</th>
		<th style="text-align: center;">Method</th>
		<th style="text-align: left;">Description</th>
		<th style="text-align: left;">Output / Status Codes</th>
		</tr>
		</thead>
		<tbody>
		<tr>
		<td style="text-align: left;"><code>/rules</code></td>
		<td style="text-align: center;"><code>GET</code></td>
		<td style="text-align: left;">Retrieves a list of all defined visibility rules.</td>
		<td style="text-align: left;"><strong>200 OK</strong>: JSON object containing an array of rules (<code>items</code>) and optional <code>nextPageToken</code>.</td>
		</tr>
		<tr>
		<td style="text-align: left;"><code>/rules</code></td>
		<td style="text-align: center;"><code>POST</code></td>
		<td style="text-align: left;">Creates a new visibility rule (server generates <code>ruleId</code>).</td>
		<td style="text-align: left;"><strong>201 Created</strong>: Returns created <code>Rule</code> object.<br><strong>400 Bad Request</strong>: Invalid input/structure.</td>
		</tr>
		<tr>
		<td style="text-align: left;"><code>/rules/{ruleId}</code></td>
		<td style="text-align: center;"><code>GET</code></td>
		<td style="text-align: left;">Retrieves details of a specific rule by ID.</td>
		<td style="text-align: left;"><strong>200 OK</strong>: <code>Rule</code> object details.<br><strong>404 Not Found</strong>: Rule does not exist.</td>
		</tr>
		<tr>
		<td style="text-align: left;"><code>/rules/{ruleId}</code></td>
		<td style="text-align: center;"><code>PATCH</code></td>
		<td style="text-align: left;">Partially updates fields in an existing rule.</td>
		<td style="text-align: left;"><strong>200 OK</strong>: Updated <code>Rule</code> object.<br><strong>400 Bad Request</strong>: Invalid payload.<br><strong>404 Not Found</strong>: Rule not found.</td>
		</tr>
		<tr>
		<td style="text-align: left;"><code>/rules/{ruleId}</code></td>
		<td style="text-align: center;"><code>DELETE</code></td>
		<td style="text-align: left;">Removes a specific rule by ID.</td>
		<td style="text-align: left;"><strong>204 No Content</strong>: Successfully deleted.<br><strong>404 Not Found</strong>: Rule not found.</td>
		</tr>
		<tr>
		<td style="text-align: left;"><code>/decision/invokers/{apiInvokerId}/discoverable-apis</code></td>
		<td style="text-align: center;"><code>GET</code> / <code>POST</code></td>
		<td style="text-align: left;">Evaluates and returns filtered discoverable APIs for the given invoker.</td>
		<td style="text-align: left;"><strong>200 OK</strong>: <code>DiscoveredAPIs</code> list matching active rules.<br><strong>400 Bad Request</strong>: Invalid parameters.<br><strong>404 Not Found</strong>: Invoker not found.</td>
		</tr>
		</tbody>
		</table>
		<hr />

public/develop/releasenotes/index.html

+33 −1

Original line number	Diff line number	Diff line
		@@ -416,6 +416,17 @@
		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#visibility-control-api" class="md-nav__link">
		<span class="md-ellipsis">

		Visibility Control API

		</span>
		</a>

		</li>

		</ul>
		@@ -2839,6 +2850,17 @@
		</span>
		</a>

		</li>

		<li class="md-nav__item">
		<a href="#visibility-control-api" class="md-nav__link">
		<span class="md-ellipsis">

		Visibility Control API

		</span>
		</a>

		</li>

		</ul>
		@@ -3731,6 +3753,14 @@
		<li>Scripts updated to include new service.</li>
		<li>CI/CD also upgraded to generate new images of this new service.</li>
		</ul>
		<h4 id="visibility-control-api"><strong>Visibility Control API</strong></h4>
		<p>Added the complete implementation of the <strong>Visibility Control API</strong> as a Helper service.</p>
		<ul>
		<li>API Providers and administrators can create, update, list, and delete visibility rules.</li>
		<li>Rules support provider selectors, invoker exceptions, default access behavior, enabled status, and validity periods.</li>
		<li>Discover service integration filters published APIs according to the active rules and the API Invoker identity.</li>
		<li>More information is available in the <a href="../features/visibility-control/visibility-control/">Visibility Control feature documentation</a>.</li>
		</ul>
		<h3 id="technical-debt-solved"><strong>Technical Debt Solved</strong></h3>
		<h4 id="upgrade-packages"><strong>Upgrade packages</strong></h4>
		<p>For security reasons:</p>
		@@ -3773,6 +3803,7 @@
		<ul>
		<li>2 New tests related with use of same apiName across different AEFs.</li>
		<li>6 new tests related with the new service OpenDiscover.</li>
		<li>12 new tests related with the Visibility Control API.</li>
		<li>Duplicate test name capif_api_provider_management-10 changed.</li>
		</ul>
		<h4 id="security-issues"><strong>Security Issues</strong></h4>
		@@ -3788,7 +3819,8 @@
		<li>New test plan section related with OpenCAPIF Interconnection.</li>
		<li>New OpenCAPIF Interconnection section under features section.</li>
		<li>New <a href="../open-discover/open-discover/">Open Discover</a> section added under Features, with a developer guide on how to call the Open Discover Service API (authentication, query parameters and error responses).</li>
		<li>New Visibility Control section under features section.</li>
		<li>New <a href="../features/visibility-control/visibility-control/">Visibility Control</a> section added under Features.</li>
		<li>New <a href="../testing/testplan/helper/visibility_control/">Visibility Control API test plan</a> added, covering visibility rule management and discoverable API filtering.</li>
		</ul>
		<h2 id="release-400"><strong>Release 4.0.0</strong></h2>
		<h3 id="visibility-control"><strong>Visibility Control</strong></h3>

public/develop/search/search_index.json

+1 −1

File changed.

Preview size limit exceeded, changes collapsed.

public/develop/sitemap.xml

+52 −52

File changed.

Preview size limit exceeded, changes collapsed.

public/develop/sitemap.xml.gz

−1 B (694 B)

File changed.

No diff preview for this file type.

View original file

View changed file