Skip to content
Snippets Groups Projects
Commit cb22ae2f authored by Jorge Moratinos's avatar Jorge Moratinos
Browse files

Merge branch 'OCF-Doc23-vendor-extensibility-documentation' into 'develop'

Resolve "Vendor extensibility Documentation"

Closes #23

See merge request !29
parents e2d29213 d22b2a14
1 merge request!29Resolve "Vendor extensibility Documentation"
Pipeline #11759 passed with stage
in 39 seconds
doc/images/vendor-ext/aef_profile.png

179 KiB

doc/images/vendor-ext/aef_profile_2.png

167 KiB

doc/images/vendor-ext/publish_supported_features.png

298 KiB

doc/images/vendor-ext/publish_supported_features_2.png

264 KiB

doc/images/vendor-ext/service_api_description.png

149 KiB

doc/images/vendor-ext/service_api_description_2.png

136 KiB

# Vendor Extensibility
Mechanism for the APIs to re-use, extend their functionalities and data models and engage with third-party API frameworks (e.g. ETSI MEC)
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.
## 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.
![Publish Supported Features](../images/vendor-ext/publish_supported_features_2.png)
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": {
...
}
```
2. domain name:
```
"vendorSpecific-3gpp.org": {
...
}
```
3. URN:
```
"vendorSpecific-urn:3gpp:example": {
...
}
```
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.
![Service API Description](../images/vendor-ext/service_api_description_2.png)
![AEF Profile](../images/vendor-ext/aef_profile_2.png)
**Example:**
ServiceAPIDescription vendorSpecific looks like:
```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"
}
}
```
AEFProfile vendorSpecific looks like:
```json
"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/"
}
}
```
Complete ETSI MEC ServiceAPIDescription with vendor extensibility would be like this:
```json
{
"apiName": "service_1",
"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"
}
},
"aefProfiles": [
{
"aefId": "string",
"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/"
}
},
"versions": [
{}
],
"protocol": "HTTP_1_1",
"dataFormat": "JSON",
"securityMethods": ["PSK"],
"interfaceDescriptions": [
{
"ipv4Addr": "string",
"port": 65535,
"securityMethods": ["PSK"]
}
]
}
],
"description": "string",
"supportedFeatures": "0",
"shareableInfo": {
"isShareable": true,
"capifProvDoms": [
"string"
]
},
"serviceAPICategory": "string",
"apiSuppFeats": "fffff",
"pubApiPath": {
"ccfIds": [
"string"
]
},
"ccfId": "string"
}
```
### 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>
}
```
**Example:**
```json
https://{{CAPIF_HOSTNAME}}:{{CAPIF_PORT}}/{{DISCOVER_URL}}?
...
vend-spec-type={
"target": "/vendorSpecific-urn:etsi:mec:capifext:transport-info",
"value": "REST_HTTP"
}
```
DOC:Work in Progress
[OCF Web]: https://ocf.etsi.org/ "OCF Web"
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment