Merge branch 'update_interconnection' into 'develop'

# OpenCAPIF Interconnection

### Overview

## Overview

OpenCAPIF Interconnection is a new functionality designed to enable seamless communication and service integration between multiple Common API Framework (CAPIF) domains, following the 3GPP specifications for CAPIF-4 and beyond. This implementation represents the first version of interconnection capabilities within the OpenCAPIF ecosystem.

3GPP Release 16 introduced CAPIF Interconnection to enable distributed deployments and interactions between different API providers. This enhancement allowed multiple CCFs — either of the same or different trust domains — to seamlessly interact, discover services, and publish APIs with one another. At the same time, CAPIF Interconnection enables API invokers to utilize the service APIs from 3rd party API providers.

### Implementation Approach

According to the specifications, CAPIF-6 or CAPIF-6e reference points have been defined to enable communication between two CCFs. Through those interfaces CCFs can: 

This implementation adheres to the 3GPP Common API Framework specifications while addressing areas where the standards provide limited definition or flexibility. We have adapted and extended the specification-defined interfaces to accommodate the specific architectural requirements of OpenCAPIF, ensuring compatibility with existing deployments while enabling cross-domain service discovery and invocation.

- publish, retrieve, update and unpublish service APIs information

- discover service APIs

- obtain security information for the API invoker upon accessing the service API, and 

- provide authorization for the API invoker prior to accessing the service API.

### Key Features

More information on CAPIF Interconnection can be found on the following Technical Specification documents:

- **Cross-Domain Service Connectivity**: Facilitates secure communication between CAPIF domains with standardized authentication and authorization mechanisms

- **Service Discovery and Registration**: Enables services to be discovered and registered across interconnected domains following 3GPP guidelines

- **Adaptive Implementation**: Custom implementations for specification gaps, designed to be interoperable and extensible for future standard updates

- 3GPP TS 23.200

  - 6.2.2 Functional model description to support CAPIF interconnection

  - 8.25 Support for CAPIF interconnection

- 3GPP TS 33.122

  - 5.3 Functional security model supporting interconnection

  - 6.13 Security procedures for CAPIF interconnection

### Specification Compliance and Extensions

## Specification Compliance and Extensions

Our approach balances strict adherence to 3GPP standards with pragmatic engineering solutions. Where the 3GPP specifications do not fully define implementation details, we have made informed design decisions that:

- Follow the architectural principles established by 3GPP

- Provide clear extension points for future standardization updates

- Ensure robust security and reliability across domain boundaries

## Implementation Approach

OpenCAPIF implementation of interconnection adheres to the 3GPP specifications while addressing areas where the standards provide limited definition. We have adapted and extended the specification-defined interfaces to accommodate the specific architectural requirements of OpenCAPIF, ensuring compatibility with existing deployments while enabling cross-domain service discovery and invocation.

OCF Release 5 implements a functional version of CAPIF interconnection capability, including all the neccessary steps described below.

### Interconnection establishment and syncronization

Interconnection establishment is initiated by the CAPIF administrator of a local CCF (CCF-A), using the "/request" API, towards a peer CCF (CCF-B).

More specifically:

POST /helper/interconnection/request with { "dstProvDom": "CCF-B host:port" }

1. If dstProvDom is already in interconnected → 409.

2. CCF-A calls CCF-B: POST https://{dstProvDom}/helper/interconnection/establish over mTLS, sending CCF-A’s ccfId, domain, CA, and public key.

3. CCF-B stores A in interconnected and replies with B’s own identity.

4. CCF-A stores that reply, then runs sync (below).

CCF administrator (either A or B) can also tear down the connection between the two CCFs

DELETE /helper/interconnection/request/{peerCcfId}

1. Peer DELETE /establish/{localCcfId}

2. On success, drop services whose apf_id is the peer CCF, pull that CCF from pubApiPath.ccfIds, delete the interconnected row.

After establishing the interconnection, the CCFs have to syncronize the state of the shared APIs. This is managed via the "/sync" API.

POST /helper/interconnection/sync from CCF-A to CCF-B.

On "/sync", the receiving CCF:

1. Looks up the caller in interconnected by dstProvDom (404 if missing).

2. Publishes (to the interconnected CCF) every local API that matches:

- shareableInfo.isShareable == true

- peer domain in shareableInfo.capifProvDoms

- apf_id is not the peer CCF (no bounce-back)

- peer CCF not already in pubApiPath.ccfIds

POST https://{dstProvDom}/published-apis/v1/{srcProvDom}/service-apis.

1. The payload sets shareableInfo.isShareable = false so the peer does not re-share.

2. Records the peer in pubApiPath.ccfIds

When CCF-B answers, CCF-A does the same in the other direction.

*CAPIF-related 3GPP standards have not yet defined exact procedures of CAPIF-6(e) interface. All the above API definition and flows are a proposed implementation of OpenCAPIF SDG contortium.* 

![CAPIF Interconnection](../images/interconnection/CAPIF_Interconnection_Establishment.png)

### Discover

Discover API has no interconnection-specific logic. It only queries the local service_api_descriptions collection and returns matching APIs. shareableInfo, pubApiPath, and ccfId appear because they are part of the 3GPP ServiceAPIDescription schema, and Discover includes them in the response

### Publish

When the interconnection capability is enabled in CCFs, the publish API flow (POST) includes the following: 

1. Normal duplicate / feature checks.

2. Read shareableInfo:

- isShareable is false or missing → local publish only.

- isShareable is true → take capifProvDoms.

1. For each domain, look up interconnected by dst_prov_dom. Unknown domain → skip. Known domain → POST the copy to that peer’s Publish API (same URL as sync, isShareable: false).

2. If any peer fails → withdraw copies already accepted, do not store locally, return 500.

3. On success, store locally and set pubApiPath.ccfIds to the peers that got a copy.

4. If the caller’s apfId contains "CCF" (incoming from a peer), that CCF is also appended to the path.

5. Cert/APF checks are skipped when the client CN is superadmin or starts with CCF. Interconnected publications have no local APF cert entry.

![Interconnection Publish POST](../images/interconnection/CAPIF_Publish_after_interconnection.png)

In case of a PUT / PATCH request:

Peers are aligned before the local write:

- domains removed from capifProvDoms → DELETE on those peers

- domains kept → PUT the new definition

- domains added → POST

- sharing turned off → unpublish from all previous domains

Peer copies are found by old apiName, because each peer assigns its own apiId. If any peer cannot be aligned, the local API is left unchanged.

In case of a DELETE request:

Unpublish from peers first, then delete locally. If a peer is unreachable, the local copy stays so the two CCFs do not drift.

![Interconnection Publish PUT PATCH DELETE](../images/interconnection/CAPIF_Publish_update_and_delete_across_CCFs.png)

### Aquire Access token

... to be added

 No newline at end of file