provider/README.md

   1 <!--
   2 -
   3 ========================LICENSE_START=================================
   4 O-RAN-SC
   5 %%
   6 Copyright (C) 2023: Nordix Foundation
   7 %%
   8 Licensed under the Apache License, Version 2.0 (the "License");
   9 you may not use this file except in compliance with the License.
  10 You may obtain a copy of the License at
  11
  12         http://www.apache.org/licenses/LICENSE-2.0
  13
  14 Unless required by applicable law or agreed to in writing, software
  15 distributed under the License is distributed on an "AS IS" BASIS,
  16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17 See the License for the specific language governing permissions and
  18 limitations under the License.
  19 ========================LICENSE_END===================================
  20
  21 -->
  22
  23 # O-RAN-SC Non-RealTime RIC CAPIF Provider Stub
  24
  25 This is a Go implementation of a stub for the CAPIF Provider function, which is 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.
  26
  27 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:
  28
  29 - Registers a new API Provider domain with API provider domain functions profiles.
  30 - Publish a new API
  31 - Retrieve all published APIs
  32
  33 ### Registers a new API Provider domain with API provider domain functions profiles.
  34
  35 This service operation is used by an API management function to register API provider domain functions as a recognized API provider of CAPIF domain.
  36
  37 <img src="docs/Register API Provider Domain.svg">
  38
  39 The request from the provider domain should include API provider Enrolment Details, consisting of details of all API provider domain functions, for example:
  40
  41 ```
  42 {
  43     "apiProvDomInfo": "Provider domain",
  44     "apiProvFuncs": [
  45         {
  46             "apiProvFuncInfo": "rApp as APF",
  47             "apiProvFuncRole": "APF",
  48             "regInfo": {
  49                 "apiProvPubKey": "APF-PublicKey"
  50             }
  51         },
  52         {
  53             "apiProvFuncInfo": "rApp as AEF",
  54             "apiProvFuncRole": "AEF",
  55             "regInfo": {
  56                 "apiProvPubKey": "AEF-PublicKey"
  57             }
  58         },
  59         {
  60             "apiProvFuncInfo": "rApp as AMF",
  61             "apiProvFuncRole": "AMF",
  62             "regInfo": {
  63                 "apiProvPubKey": "AMF-PublicKey"
  64             }
  65         },
  66         {
  67             "apiProvFuncInfo": "Gateway as entrypoint AEF",
  68             "apiProvFuncRole": "AEF",
  69             "regInfo": {
  70                 "apiProvPubKey": "AEF-Gateway-PublicKey"
  71             }
  72         }
  73     ],
  74     "regSec": "PSK"
  75 }
  76 ```
  77
  78 The CAPIF core proceeds to register the provider and creates Ids for the API provider domain functions that will be return as part of the response message.
  79
  80 ### Publish a new API
  81
  82 This service operation is used by an API publishing function to publish service APIs on the CAPIF core function.
  83
  84 <img src="docs/Publish a new API.svg">
  85
  86 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.
  87
  88 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.
  89
  90 The Service API information includes:
  91 - Service API name
  92 - API provider name (optional)
  93 - Service API type
  94 - Communication type
  95 - Serving Area Information (optional)
  96 - AEF location (optional)
  97 - Interface details (e.g. IP address, port number, URI)
  98 - Protocols
  99 - Version numbers
 100 - Data format
 101
 102 ```
 103 {
 104     "apiName": "example",
 105     "description": "Example API of rApp B",
 106     "aefProfiles": [
 107         {
 108             "aefId": "AEF_id_rApp_as_AEF",
 109             "description": "Example rApp B as AEF",
 110             "versions": [
 111                 {
 112                     "apiVersion": "v1",
 113                     "resources": [
 114                         {
 115                             "resourceName": "example",
 116                             "commType": "REQUEST_RESPONSE",
 117                             "uri": "/example/subscription/subscription_id_1",
 118                             "operations": [
 119                                 "GET"
 120                             ]
 121                         }
 122                     ]
 123                 }
 124             ],
 125             "protocol": "HTTP_1_1",
 126                         "securityMethods": ["PSK"],
 127                         "interfaceDescriptions": [
 128                                 {
 129                                   "ipv4Addr": "string",
 130                                   "port": 65535,
 131                                   "securityMethods": ["PKI"]
 132                                 },
 133                                 {
 134                                   "ipv4Addr": "string",
 135                                   "port": 65535,
 136                                   "securityMethods": ["PKI"]
 137                                 }
 138                           ]
 139         }
 140     ]
 141 }
 142 ```
 143
 144
 145 ### Retrieve all published APIs
 146
 147 This service operation is used by an API publishing function to retrieve service APIs from the CAPIF core function.
 148
 149 <img src="docs/Retrieve all published APIs.svg">
 150
 151 Respond includes requested API Information.
 152
 153 ## Build application
 154
 155 To build the application, run the following command:
 156
 157     go build
 158
 159 The application can also be built as a Docker image, by using the following command:
 160
 161     docker build . -t capifprov
 162
 163 ## Run
 164
 165 To run the provider from the command line, run the following commands from this folder.
 166
 167     ./capifprov [-port <port (default 9090)>] [-capifCoreUrl <URL to Capif core (default http://localhost:8090)>] [-loglevel <log level (default Info)>]