Additional Info on Vendor Extensibility

# Vendor Extensibility

This is a mechanism for the APIs to re-use, extend their functionalities and data models and engage with third-party API frameworks. 

Mechanism for the APIs to re-use, extend their functionalities and data models and engage with third-party API frameworks (e.g. ETSI MEC)

Is defined on 3GPP TS 29.122 and 29.500 and is tightly connected with “supported-features” and feature negotiation

Vendor specific extensions are defined on 3GPP TS 29.122 (section 5.2.13) and 29.500 (section 6.6.3) and is tightly connected with "supported-features” and "feature negotiation" procedures.

## Supported Features in Publish API:

![Publish Supported Features](../images/vendor-ext/publish_supported_features.png)

## Vendor Extensibility in CAPIF:

Vendor Extensibility is a feature focused on the APIs that are published and exposed via CAPIF. 

As a result, the feature is supported by the ServiceAPIDescription object (and any other objects embeded on it e.g. AefProfile). In the figure below, depicting all supported features of ServiceAPIDescription, 

VendExt feature is noted, which enables vendor-specific extension in the body of the specific object.

## Vendor extensions Data Models

![Publish Supported Features](../images/vendor-ext/publish_supported_features_2.png)

* Extend the information element with vendor specific fields

### Fields have specific naming schemes:

* Using the 6-digit IANA-assigned enterprise code:

Vendor extensibility feature can be enabled and leveraged in 2 CAPIF APIs, Publish and Discover.

## Vendor Extensibility in CAPIF APIs 

### Publish API:

A vendor can extend the ServiceAPIDescription object by adding additional member elements. However, in order to avoid duplication of member names inside a same object 

it is necessary to comply with a naming scheme for vendor-specific data elements, to avoid clashing names between vendors.

Vendor-specific member names in JSON objects shall be named in the following manner:

```

  "vendorSpecific-nnnnnnnnn": {

        ...

        }

```

where the value "nnnnnn" can be:

1.  6-digit IANA-assigned enterprise code:

```

  "vendorSpecific-010415": {

        }

```

* Using domain name:

2.  domain name:

```

        }

```

* Using URN:

3. URN:

```

        }

```

**Service API Description and AEF Profile Data**

![Service API Description](../images/vendor-ext/service_api_description.png)

A concrete example of vendor-specific extensibility exists on section 9 of ETSI GS MEC 011 V3.2.1, where ETSI MEC extends the ServiceAPIDescription as depicted on the following two figures.

![AEF Profile](../images/vendor-ext/aef_profile.png)

![Service API Description](../images/vendor-ext/service_api_description_2.png)

![AEF Profile](../images/vendor-ext/aef_profile_2.png)

### Discover Query Parameters

**Example:**

```json

"vendorSpecific-urn:etsi:mec:capifext:service-info": {

      "serializer": "JSON",

      "state": "ACTIVE",

      "scopeOfLocality": "MEC_SYSTEM",

      "consumedLocalOnly": "True",

      "isLocal": "True",

      "category": {

          "href": "https://www.location.com",

          "id": "location_1",

          "name": "Location",

          "version": "1.0"

      }

  }

* Provisioning of vendor-specific query parameters to support additional vendor-specific filtering criteria

### A vendor-specific query parameter shall be encoded as follows:

  "vendorSpecific-urn:etsi:mec:capifext:transport-info": {

      "name": "trasport1",

      "description": "Transport Info 1",

      "type": "REST_HTTP",

      "protocol": "HTTP",

      "version": "2",

      "security": {

          "grantTypes": "OAUTH2_CLIENT_CREDENTIALS",

          "tokenEndpoint": "https://token-endpoint/"

      }

  }

```

* query parameter name: 

### Discover API

In order to use vendor-specific fields as filters in Discover API, vendor-specific query parameter shall be encoded as follows:

```json

https://{{CAPIF_HOSTNAME}}:{{CAPIF_PORT}}/{{DISCOVER_URL}}?

       ...

       vend-spec-<query parameter name>={

          "target": <string that contains the JSON pointer to the attribute in the resource representation>, 

          "value": <query parameter value>

}

```

"vend-spec-<query parameter name>”

```

* query parameter value encoded as JSON object:

    * "target" 

    * "value"

**Example:**

```

GET {apiRoot}/3gpp-monitoring-event/v1/{scsAsId}/subscriptions?vend-spec-max-reports={"target": "/maximumNumberOfReports", value: "6"} 

```json

    https://{{CAPIF_HOSTNAME}}:{{CAPIF_PORT}}/{{DISCOVER_URL}}?

           ...

           vend-spec-type={

              "target": "/vendorSpecific-urn:etsi:mec:capifext:transport-info", 

              "value": "REST_HTTP"

    }

```