From 369de53fafc96b544add3d002c874d13352f824c Mon Sep 17 00:00:00 2001 From: ychacon Date: Mon, 29 May 2023 11:57:06 +0200 Subject: [PATCH] Adding documentation for provider Issue-ID: NONRTRIC-861 Signed-off-by: ychacon Change-Id: Id74b4750f1f4bd48e06e18bb6760778dfb5c4ac3 --- provider/Dockerfile | 6 +- provider/README.md | 167 +++++++++++++++++++++++++ provider/docs/Publish a new API.svg | 35 ++++++ provider/docs/Register API Provider Domain.svg | 28 +++++ provider/docs/Retrieve all published APIs.svg | 25 ++++ provider/docs/publishapi.plantuml | 25 ++++ provider/docs/registerproviderdomain.plantuml | 18 +++ provider/docs/retrievepublishedapi.plantuml | 15 +++ 8 files changed, 316 insertions(+), 3 deletions(-) create mode 100644 provider/README.md create mode 100644 provider/docs/Publish a new API.svg create mode 100644 provider/docs/Register API Provider Domain.svg create mode 100644 provider/docs/Retrieve all published APIs.svg create mode 100644 provider/docs/publishapi.plantuml create mode 100644 provider/docs/registerproviderdomain.plantuml create mode 100644 provider/docs/retrievepublishedapi.plantuml diff --git a/provider/Dockerfile b/provider/Dockerfile index bfadfb8..8c421a1 100644 --- a/provider/Dockerfile +++ b/provider/Dockerfile @@ -26,13 +26,13 @@ COPY go.mod . COPY go.sum . RUN go mod download COPY . . -RUN go build -o /capifprovider +RUN go build -o /capif-stub-provider ## ## Deploy ## FROM gcr.io/distroless/base-debian11 WORKDIR / ## Copy from "build" stage -COPY --from=build /capifprovider . +COPY --from=build /capif-stub-provider . USER nonroot:nonroot -ENTRYPOINT ["/capifprovider"] +ENTRYPOINT ["/capif-stub-provider"] diff --git a/provider/README.md b/provider/README.md new file mode 100644 index 0000000..cd0e2a9 --- /dev/null +++ b/provider/README.md @@ -0,0 +1,167 @@ + + +# O-RAN-SC Non-RealTime RIC CAPIF Provider Stub + +This is a Go implementation of a stub for the CAPIF Provider function, based on the 3GPP "29.222 Common API Framework for 3GPP Northbound APIs (CAPIF)" interfaces, see https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=3450. + +This stub offers a user interface that helps to test the functionalities implemented in the O-RAN-SC Capif implementation and the supported features are the following: + +- Registers a new API Provider domain with API provider domain functions profiles. +- Publish a new API +- Retrieve all published APIs + +### Registers a new API Provider domain with API provider domain functions profiles. + +This service operation is used by an API management function to register API provider domain functions as a recognized API provider of CAPIF domain. + + + +The request from the provider domain should include API provider Enrolment Details, consisting of details of all API provider domain functions, for example: + +``` +{ + "apiProvDomInfo": "Provider domain", + "apiProvFuncs": [ + { + "apiProvFuncInfo": "rApp as APF", + "apiProvFuncRole": "APF", + "regInfo": { + "apiProvPubKey": "APF-PublicKey" + } + }, + { + "apiProvFuncInfo": "rApp as AEF", + "apiProvFuncRole": "AEF", + "regInfo": { + "apiProvPubKey": "AEF-PublicKey" + } + }, + { + "apiProvFuncInfo": "rApp as AMF", + "apiProvFuncRole": "AMF", + "regInfo": { + "apiProvPubKey": "AMF-PublicKey" + } + }, + { + "apiProvFuncInfo": "Gateway as entrypoint AEF", + "apiProvFuncRole": "AEF", + "regInfo": { + "apiProvPubKey": "AEF-Gateway-PublicKey" + } + } + ], + "regSec": "PSK" +} +``` + +The CAPIF core proceeds to register the provider and creates Ids for the API provider domain functions that will be return as part as the response message. + +### Publish a new API + +This service operation is used by an API publishing function to publish service APIs on the CAPIF core function. + + + +The CAPIF supports publishing service APIs by the API provider. The API publishing function can be within PLMN trust domain or within 3rd party trust domain. + +In order to publish a new API, the APF should be registered in the CAPIF core (apfId is required) along with the Service API information. + +The Service API information includes: +- Service API name +- API provider name (optional) +- Service API type +- Communication type +- Serving Area Information (optional) +- AEF location (optional) +- Interface details (e.g. IP address, port number, URI) +- Protocols +- Version numbers +- Data format + +``` +{ + "apiName": "example", + "description": "Example API of rApp B", + "aefProfiles": [ + { + "aefId": "AEF_id_rApp_as_AEF", + "description": "Example rApp B as AEF", + "versions": [ + { + "apiVersion": "v1", + "resources": [ + { + "resourceName": "example", + "commType": "REQUEST_RESPONSE", + "uri": "/example/subscription/subscription_id_1", + "operations": [ + "GET" + ] + } + ] + } + ], + "protocol": "HTTP_1_1", + "securityMethods": ["PSK"], + "interfaceDescriptions": [ + { + "ipv4Addr": "string", + "port": 65535, + "securityMethods": ["PKI"] + }, + { + "ipv4Addr": "string", + "port": 65535, + "securityMethods": ["PKI"] + } + ] + } + ] +} +``` + + +### Retrieve all published APIs + +This service operation is used by an API publishing function to retrieve service APIs from the CAPIF core function. + + + +Respond includes requested API Information. + +## Build application + +To build the application, run the following command: + + go build + +The application can also be built as a Docker image, by using the following command: + + docker build . -t capifprov + +## Run + +To run the provider from the command line, run the following commands from this folder. + + ./capifprov [-port ] [-capifCoreUrl ] [-loglevel ] diff --git a/provider/docs/Publish a new API.svg b/provider/docs/Publish a new API.svg new file mode 100644 index 0000000..7162914 --- /dev/null +++ b/provider/docs/Publish a new API.svg @@ -0,0 +1,35 @@ +CAPIF InternalProviderClientProviderClientcapifcorecapifcoreprovidermanagerprovidermanagerpublishservicepublishserviceeventserviceeventserviceinvokerinvokeralt[Publish Service]Publish serviceswith providerIdandServiceAPIDescriptionPublish servicesAre AEFs registeredfor provider?OkCreate apiIdalt[Subcribed Event Handling]Service publishedCAPIFEventDetailServiceAPIDescriptionwith apiIdServiceAPIDescriptionwith apiId \ No newline at end of file diff --git a/provider/docs/Register API Provider Domain.svg b/provider/docs/Register API Provider Domain.svg new file mode 100644 index 0000000..9308c71 --- /dev/null +++ b/provider/docs/Register API Provider Domain.svg @@ -0,0 +1,28 @@ +CAPIF InternalProviderClientProviderClientcapifcorecapifcoreprovidermanagerprovidermanagerpublishservicepublishservicealt[Provider Enrolment]Register provider withAPIProviderEnrolmentDetailsRegister providerCreate apiProvDomIdand apiProvFuncIdsfor provided functionsProvider withapfId and aefIdsProvider withapfId and aefIds \ No newline at end of file diff --git a/provider/docs/Retrieve all published APIs.svg b/provider/docs/Retrieve all published APIs.svg new file mode 100644 index 0000000..b2e1e22 --- /dev/null +++ b/provider/docs/Retrieve all published APIs.svg @@ -0,0 +1,25 @@ +CAPIF InternalProviderClientProviderClientcapifcorecapifcorepublishservicepublishservicealt[Retrieve API Service]Retrieve serviceswith apfIdRetrieve all publishedservices from apfIdArray of ServiceAPIDescriptionAll ServiceAPIDescriptionpublished from apfId \ No newline at end of file diff --git a/provider/docs/publishapi.plantuml b/provider/docs/publishapi.plantuml new file mode 100644 index 0000000..28c7767 --- /dev/null +++ b/provider/docs/publishapi.plantuml @@ -0,0 +1,25 @@ +@startuml Publish a new API +actor ProviderClient +box "CAPIF Internal" +participant capifcore +participant providermanager +participant publishservice +participant eventservice +end box +actor invoker + +alt#LightBlue #LightBlue Publish Service + ProviderClient->capifcore: Publish services\n with providerId\n andServiceAPIDescription + capifcore->publishservice: Publish services + publishservice->providermanager: Are AEFs registered\n for provider? + providermanager->publishservice: Ok + publishservice->publishservice: Create apiId + alt#Orange #Orange Subcribed Event Handling + publishservice->eventservice: Service published + eventservice->invoker: CAPIFEventDetail + end + publishservice->capifcore: ServiceAPIDescription\n with apiId + capifcore->ProviderClient: ServiceAPIDescription\n with apiId +end + +@enduml \ No newline at end of file diff --git a/provider/docs/registerproviderdomain.plantuml b/provider/docs/registerproviderdomain.plantuml new file mode 100644 index 0000000..a16150e --- /dev/null +++ b/provider/docs/registerproviderdomain.plantuml @@ -0,0 +1,18 @@ +@startuml Register API Provider Domain +actor ProviderClient +box "CAPIF Internal" +participant capifcore +participant providermanager +participant publishservice + +end box + +alt#paleGreen #paleGreen Provider Enrolment + ProviderClient->capifcore: Register provider with\n APIProviderEnrolmentDetails + capifcore->providermanager:Register provider + providermanager->providermanager: Create apiProvDomId\n and apiProvFuncIds\n for provided functions + providermanager->capifcore: Provider with\n apfId and aefIds + capifcore->ProviderClient: Provider with\n apfId and aefIds +end + +@enduml \ No newline at end of file diff --git a/provider/docs/retrievepublishedapi.plantuml b/provider/docs/retrievepublishedapi.plantuml new file mode 100644 index 0000000..6fd3874 --- /dev/null +++ b/provider/docs/retrievepublishedapi.plantuml @@ -0,0 +1,15 @@ +@startuml Retrieve all published APIs +actor ProviderClient +box "CAPIF Internal" +participant capifcore +participant publishservice +end box + +alt#Salmon #Salmon Retrieve API Service + ProviderClient->capifcore: Retrieve services\n with apfId + capifcore->publishservice: Retrieve all published\n services from apfId + publishservice->capifcore: Array of ServiceAPIDescription + capifcore->ProviderClient: All ServiceAPIDescription\n published from apfId +end + +@enduml \ No newline at end of file -- 2.16.6