From f5cc4c5773b4b4eae42de7b3206b78dfeaf4d90c Mon Sep 17 00:00:00 2001 From: elinuxhenrik Date: Tue, 6 Dec 2022 17:30:10 +0100 Subject: [PATCH] Add the rest of the apis to the diagrams Issue-ID: NONRTRIC-814 Signed-off-by: elinuxhenrik Change-Id: Icb70325398a4dbafcb1c23535ca5ef792d98af3c --- capifcore/README.md | 21 +- .../diagrams/Information in rApp registration.svg | 515 ++---------- .../docs/diagrams/Information model for CAPIF.svg | 884 +++++++++++++++++++++ capifcore/docs/diagrams/Register Provider.svg | 79 +- capifcore/docs/diagrams/classdiagram.plantuml | 166 +++- .../diagrams/classdiagramregistration.plantuml | 158 ++++ .../registerpoviderandpublishservice.plantuml | 77 +- 7 files changed, 1326 insertions(+), 574 deletions(-) create mode 100644 capifcore/docs/diagrams/Information model for CAPIF.svg create mode 100644 capifcore/docs/diagrams/classdiagramregistration.plantuml diff --git a/capifcore/README.md b/capifcore/README.md index e561d63..4ccb557 100644 --- a/capifcore/README.md +++ b/capifcore/README.md @@ -24,16 +24,22 @@ This product is a Go implementation of the CAPIF Core 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. -The data used within CAPIF Core is shown in the diagram below. +The, almost, complete data model for CAPIF is shown in the diagram below. + + + +The data used within CAPIF Core for registering an rApp that both provides and consumes services is shown in the diagram below. -An example of how an rApp that both exposes and consumes services can be registered in CAPIF Core is shown in the sequence diagram below. Discovery of services for an invoker is also shown. +An example of how an rApp that both provides and consumes services can be registered in CAPIF Core is shown in the sequence diagram below. Discovery of services, request for access token and event subscription for an invoker is also shown. -***NOTE!*** It has not been decided that CAPIF Core will actually do the Helm chart installation. This is just provided in the prototype as an example of what CAPIF Core could do. Before publishing a service, the chart that belongs to the service must be registered in ChartMuseum. When publishing the service the following information should be provided in the `ServiceAPIDescription::description` attribute; "namespace", "repoName", "chartName", "releaseName". An example of the information: "Description of rApp helloWorld,namespace,repoName,chartName,releaseName". +***NOTE!*** It has not been decided that CAPIF Core will actually do the Helm chart installation. This is just provided in the prototype as an example of what CAPIF Core could do. +If Helm is used, before publishing a service, the chart that belongs to the service must be registered in ChartMuseum. When publishing the service the following information should be provided in the `ServiceAPIDescription::description` attribute; "namespace", "repoName", "chartName", "releaseName". An example of the information: "Description of rApp helloWorld,namespace,repoName,chartName,releaseName". + ## Generation of API code The CAPIF APIs are generated from the OpenAPI specifications provided by 3GPP. The `generate.sh` script downloads the @@ -53,10 +59,11 @@ To fix the specifications there are three tools: When a dependency to a new specification is introduced in any of the CAPIF specifications, see example below, the following steps should be performed: For the CAPIF specification "TS29222_CAPIF_Discover_Service_API" a new dependency like the following has been introduced. -websockNotifConfig: -    $ref: '**TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig**' -1. Copy the bold part of the reference and add it to the `definitions.txt` file. This step is not needed if the type is already defined in the file. + websockNotifConfig: + $ref: ✅TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig✅' + +1. Copy the part between the checkboxes of the reference and add it to the `definitions.txt` file. This step is not needed if the type is already defined in the file. 2. Look in the `generate.sh` script, between the "" and "" tags, to see if "TS29122_CommonData" has already been replaced in "TS29222_CAPIF_Discover_Service_API". 3. If it has not been replaced, add a replacement above the "" tag by copying and adapting the two rows above the tag. @@ -89,4 +96,4 @@ To run the Core Function from the command line, run the following commands from ./capifcore [-port ] [-chartMuseumUrl ] [-repoName ] [-loglevel ] -To run CAPIF Core as a K8s pod together with ChartMuseum, start and stop scripts are provided. The pod configurations are provided in the `configs` folder. CAPIF Core is then available att port `31570`. +To run CAPIF Core as a K8s pod together with ChartMuseum, start and stop scripts are provided. The pod configurations are provided in the `configs` folder. CAPIF Core is then available on port `31570`. diff --git a/capifcore/docs/diagrams/Information in rApp registration.svg b/capifcore/docs/diagrams/Information in rApp registration.svg index 2ce5f1a..45e2a54 100644 --- a/capifcore/docs/diagrams/Information in rApp registration.svg +++ b/capifcore/docs/diagrams/Information in rApp registration.svg @@ -1,88 +1,51 @@ -Provider ServicePublish ServiceInvoker ManagementDiscover ServiceSecurity ServiceEvent ServiceAccess Control PolicyAPIProviderEnrolmentDetailsstring apiProvDomIdstring apiProvDomInfo[]APIProviderFunctionDetails apiProvFuncsstring regSec (required)Id provided by CAPIF CoreAPIProviderFunctionDetailsstring apiProvFuncIdstring apiProvFuncInfoApiProviderFuncRole apiProviderFuncRole (required)RegistrationInformation regInfo (required)Id provided by CAPIF CoreApiProviderFuncRoleAEF: API provider function is API Exposing Function.APF: API provider function is API Publishing Function.AMF: API Provider function is API Management Function.RegistrationInformationstring apiProvCertstring apiProvPubKey (required)ServiceAPIDescriptionstring apiIdstring description[]AefProfile aefProfilesstring apiName (required)Id provided by CAPIF CoreapfId matchingAPIProviderFunctionDetails::apiProvFuncIdmust be provided when publishingAefProfileDataFormat dataFormatstring domainName[]InterfaceDescription interfaceDescriptionsProtocol protocol[]SecurityMethod securityMethodsstring aefId (required)[]Version versions (required)DataFormatJSONProtocolHTTP_1_1HTTP_2AefProfile::aefId should matchAPIProviderFunctionDetails::apiProvFuncIdInterfaceDescriptionstring ipv4Addressstring ipv6Addressint port[]SecurityMethod securityMethodsSecurity methods supported by the interface,it take precedence over the security methodsprovided in AefProfile, for this specific interface.Version[]CustomOperation custOperationsDateTime expiry[]Resource resourcesstring apiVersion (required)CustomOperationstring description[]Operation operationsCommunicationType commType (required)string custOpName (required)OperationGETPOSTPUTPATCHDELETESecurityMethodPSKPKIOAUTHResourcestring descriptionstring resourceName (required)string uri (required)CommunicationType commType (required)CommunicationTypeREQUEST_RESPONSESUBSCRIBE_NOTIFYAPIInvokerEnrolmentDetailsstring apiInvokerIdstring apiInvokerInformationAPIList apiListOnboardingInformation onboardingInformation (required)OnboardingInformationstring apiInvokerCertificatestring onboardingSecretstring ApiInvokerPublicKey (required)DiscoveredAPIs[]ServiceAPIDescription serviceAPIDescriptionsAccessTokenReqstring client_secretstring scopestring grant_type (required)string client_id (required)AccessTokenRspstring scopestring access_token (required)string token_type (required)DurationSec expires_in (required)EventSubscriptionReportingInformation eventReq[]CAPIFEventFilter eventFilters[]CAPIFEvent events (required)Uri notificationDestination (required)CAPIFEventFilter[]string aefIds[]string apiIds[]string apiInvokerIdsCAPIFEventSERVICE_API_AVAILABLESERVICE_API_UNAVAILABLESERVICE_API_UPDATEAPI_INVOKER_ONBOARDEDAPI_INVOKER_OFFBOARDEDSERVICE_API_INVOCATION_SUCCESSSERVICE_API_INVOCATION_FAILUREACCESS_CONTROL_POLICY_UPDATEACCESS_CONTROL_POLICY_UNAVAILABLEAPI_INVOKER_AUTHORIZATION_REVOKEDAPI_INVOKER_UPDATEDAPI_TOPOLOGY_HIDING_CREATEDAPI_TOPOLOGY_HIDING_REVOKEDReportingInformationDurationSec grpRepTimebool immRepUinteger maxReportNbrNotificationFlag notifFlagNotificationMethod notifMethodPartitioningCriteria partitionCriteriaDurationSec repPeriodSamplingRation sampRatioCAPIFEventDetailAccessControlPolicyListExt accCtrlPolList[]string apiIds[]string apiInvokerIds[]ServiceAPIDescription serviceAPIDescriptionsAccessControlPolicyListExtAccessControlPolicyList accessControlPolicyListstring apiIdAccessControlPolicyList[]ApiInvokerPolicy apiInvokerPoliciesApiInvokerPolicy[]TimeRangeList allowedInvocationTimeRangeListint allowedInvocationsPerSecondint allowedTotalInvocationsstring apiInvokerId (required)TimeRangeListDateTime startTimeDateTime stopTimeId provided by CAPIF CoreSecret provided by CAPIF CoreServices can only be discoveredfor an onboarded invoker throughAPIInvokerEnrolmentDetails::apiInvokerIdAccessTokenReq::client_id andAccessTokenReq::client_secretmust match registered invokerFunction provided inAccessTokenReq:scopemust be registered for a providerAPI provided inAccessTokenReq:scopemust be published11..N111111..N11..N0..10..111..N0..10..N11..N11..N1..N1..N0..10..N110..N0..N11APIList containing servicesavailable for the invoker.Provided by capifcore11..N110..N0..N0..N0..N11..N0..N0..N0..N0..N0..N0..N0..N0..N0..N0..N0..N0..NProvider ServicePublish ServiceInvoker ManagementDiscover ServiceAPIProviderEnrolmentDetailsstring apiProvDomIdstring apiProvDomInfo[]APIProviderFunctionDetails apiProvFuncsstring regSec (required)Id provided by CAPIF CoreAPIProviderFunctionDetailsstring apiProvFuncIdstring apiProvFuncInfoApiProviderFuncRole apiProviderFuncRole (required)RegistrationInformation regInfo (required)Id provided by CAPIF CoreApiProviderFuncRoleAEF: API provider function is API Exposing Function.APF: API provider function is API Publishing Function.AMF: API Provider function is API Management Function.RegistrationInformationstring apiProvCertstring apiProvPubKey (required)ServiceAPIDescriptionstring apiIdstring description[]AefProfile aefProfilesstring apiName (required)Id provided by CAPIF CoreapfId matchingAPIProviderFunctionDetails::apiProvFuncIdmust be provided when publishingAefProfileDataFormat dataFormatstring domainName[]InterfaceDescription interfaceDescriptionsProtocol protocol[]SecurityMethod securityMethodsstring aefId (required)[]Version versions (required)DataFormatJSONProtocolHTTP_1_1HTTP_2AefProfile::aefId should matchAPIProviderFunctionDetails::apiProvFuncIdInterfaceDescriptionstring ipv4Addressstring ipv6Addressint port[]SecurityMethod securityMethodsSecurity methods supported by the interface,it take precedence over the security methodsprovided in AefProfile, for this specific interface.Version[]CustomOperation custOperationsDateTime expiry[]Resource resourcesstring apiVersion (required)CustomOperationstring description[]Operation operationsCommunicationType commType (required)string custOpName (required)OperationGETPOSTPUTPATCHDELETESecurityMethodPSKPKIOAUTHResourcestring descriptionstring resourceName (required)string uri (required)CommunicationType commType (required)CommunicationTypeREQUEST_RESPONSESUBSCRIBE_NOTIFYAPIInvokerEnrolmentDetailsstring apiInvokerIdstring apiInvokerInformationAPIList apiListOnboardingInformation onboardingInformation (required)OnboardingInformationstring apiInvokerCertificatestring onboardingSecretstring ApiInvokerPublicKey (required)Secret provided by CAPIF CoreId provided by CAPIF CoreDiscoveredAPIs[]ServiceAPIDescription serviceAPIDescriptionsServices can only be discoveredfor an onboarded invoker throughAPIInvokerEnrolmentDetails::apiId11..N111111..N11..N0..10..111..N0..10..N11..N11..N1..N1..N0..10..N110..N0..N11APIList containing servicesavailable for the invoker.Provided by capifcore11..N110..N0..NProvider ServicePublish ServiceInvoker ManagementDiscover ServiceSecurity ServiceEvent ServiceAccess Control PolicyLogging ServiceAuditing ServiveRouting ServiceAPIProviderEnrolmentDetailsstring apiProvDomIdstring apiProvDomInfo[]APIProviderFunctionDetails apiProvFuncsSupportedFeatures suppFeatsstring regSec (required)Id provided by CAPIF CoreAPIProviderFunctionDetailsstring apiProvFuncIdstring apiProvFuncInfoApiProviderFuncRole apiProviderFuncRole (required)RegistrationInformation regInfo (required)Id provided by CAPIF CoreApiProviderFuncRoleAEF: API provider function is API Exposing Function.APF: API provider function is API Publishing Function.AMF: API Provider function is API Management Function.RegistrationInformationstring apiProvCertstring apiProvPubKey (required)ServiceAPIDescriptionstring apiIdstring description[]AefProfile aefProfilesSupportedFeatures apiSuppFeatSupportedFeatures supportedFeaturesstring apiName (required)Id provided by CAPIF CoreapfId matchingAPIProviderFunctionDetails::apiProvFuncIdmust be provided when publishingAefProfileDataFormat dataFormatstring domainName[]InterfaceDescription interfaceDescriptionsProtocol protocol[]SecurityMethod securityMethodsstring aefId (required)[]Version versions (required)DataFormatJSONProtocolHTTP_1_1HTTP_2AefProfile::aefId should matchAPIProviderFunctionDetails::apiProvFuncIdInterfaceDescriptionstring ipv4Addressstring ipv6Addressint port[]SecurityMethod securityMethodsSecurity methods supported by the interface,it take precedence over the security methodsprovided in AefProfile, for this specific interface.Version[]CustomOperation custOperationsDateTime expiry[]Resource resourcesstring apiVersion (required)CustomOperationstring description[]Operation operationsCommunicationType commType (required)string custOpName (required)OperationGETPOSTPUTPATCHDELETESecurityMethodPSKPKIOAUTHResourcestring descriptionstring resourceName (required)string uri (required)CommunicationType commType (required)CommunicationTypeREQUEST_RESPONSESUBSCRIBE_NOTIFYAPIInvokerEnrolmentDetailsstring apiInvokerIdstring apiInvokerInformationAPIList apiListSupportedFeatures supportedFeaturesOnboardingInformation onboardingInformation (required)Id provided byCAPIF CoreOnboardingInformationstring apiInvokerCertificatestring onboardingSecretstring ApiInvokerPublicKey (required)Secret providedby CAPIF CoreDiscoveredAPIs[]ServiceAPIDescription serviceAPIDescriptionsAccessTokenReqstring client_secretstring scopestring grant_type (required)string client_id (required)AccessTokenRspstring scopestring access_token (required)string token_type (required)DurationSec expires_in (required)ServiceSecuritySupportedFeatures supportedFeatures[]SecurityInformation securityInfo (required)SecurityInformationstring aefIdstring apiIdstring authenticationInfostring authorizationInfoInterfaceDescription interfaceDetails[]SecurityMethod prefSecurityMethods[]SecurityMethod selSecurityMethodsEventSubscriptionReportingInformation eventReq[]CAPIFEventFilter eventFiltersSupportedFeatures supportedFeatures[]CAPIFEvent events (required)Uri notificationDestination (required)CAPIFEventFilter[]string aefIds[]string apiIds[]string apiInvokerIdsCAPIFEventSERVICE_API_AVAILABLESERVICE_API_UNAVAILABLESERVICE_API_UPDATEAPI_INVOKER_ONBOARDEDAPI_INVOKER_OFFBOARDEDSERVICE_API_INVOCATION_SUCCESSSERVICE_API_INVOCATION_FAILUREACCESS_CONTROL_POLICY_UPDATEACCESS_CONTROL_POLICY_UNAVAILABLEAPI_INVOKER_AUTHORIZATION_REVOKEDAPI_INVOKER_UPDATEDAPI_TOPOLOGY_HIDING_CREATEDAPI_TOPOLOGY_HIDING_REVOKEDReportingInformationDurationSec grpRepTimebool immRepUinteger maxReportNbrNotificationFlag notifFlagNotificationMethod notifMethodPartitioningCriteria partitionCriteriaDurationSec repPeriodSamplingRation sampRatioCAPIFEventDetailAccessControlPolicyListExt accCtrlPolList[]string apiIds[]string apiInvokerIds[]ServiceAPIDescription serviceAPIDescriptionsAccessControlPolicyListExtAccessControlPolicyList accessControlPolicyListstring apiIdAccessControlPolicyList[]ApiInvokerPolicy apiInvokerPoliciesApiInvokerPolicy[]TimeRangeList allowedInvocationTimeRangeListint allowedInvocationsPerSecondint allowedTotalInvocationsstring apiInvokerId (required)TimeRangeListDateTime startTimeDateTime stopTimeInvocationLogSupportedFeatures supportedFeaturesstring aefId (required)string apiInvokerId (required)[]Log logs (required)LogInterfaceDescription destInterfacestring fwdInterfaceinterface inputParametersDurationMs invocationLatencyDateTime invocationTimeOperation operationinterface outputParametersInterfaceDescription srcInterfaceUri uristring apiId (required)string apiName (required)string apiVersion (required)Protocol protocol (required)string resourceName (required)string result (required)GetApiInvocationLogsParamsstring aefIdstring apiInvokerIdDateTime timeRangeStartDateTime timeRangeEndstring apiIdstring apiNamestring apiVersionProtocol protocolOperation operationstring resultstring resourceNameInterfaceDescription srcInterfaceRoutingInfo[]RoutingRule routingRules (required)RoutingRule[]Ipv4AddressRange ipv4AddrRanges[]Ipv6AddressRange ipv6AddrRangesAefProfile aefProfile (required)GetServiceApisServiceApiIdParamsSupportedFeatures suppFeatstring aefId (required)A call withGetServiceApisServiceApiIdParamsreturns a RoutingRuleAPIList containing servicesavailable for the invoker.Provided by capifcoreServices can only be discoveredfor an onboarded invoker throughAPIInvokerEnrolmentDetails::apiInvokerIdAccessTokenReq::client_id andAccessTokenReq::client_secretmust match registered invokerFunction provided inAccessTokenReq:scopemust be registered for a providerAPI provided inAccessTokenReq:scopemust be publishedA call withGetApiInvocationLogsParamsreturns an InvocationLog11..N111111..N11..N0..10..111..N0..10..N11..N11..N1..N1..N0..10..N110..N0..N1111..N110..N0..N11..N0..10..N11..N0..10..N0..N0..N11..N0..N0..N0..N0..N0..N0..N0..N0..N0..N0..N0..N0..N11..N0..10..N0..10..N0..10..N0..10..N0..10..10..10..10..10..111..N11 \ No newline at end of file diff --git a/capifcore/docs/diagrams/Register Provider.svg b/capifcore/docs/diagrams/Register Provider.svg index 27b89bb..71ba3e8 100644 --- a/capifcore/docs/diagrams/Register Provider.svg +++ b/capifcore/docs/diagrams/Register Provider.svg @@ -1,4 +1,4 @@ -CAPIF InternalrAppCataloguerAppCataloguerApprApprAppManagerrAppManagercapifcorecapifcoreprovidermanagerprovidermanagerhelmmanagerhelmmanagerpublishservicepublishserviceinvokerserviceinvokerservicediscoverservicediscoverservicesecurityservicesecurityserviceeventserviceeventserviceStart rApp, with rAppdescriptor specifying whichservices to expose and consumealt[Provider Enrolment]Register provider withAPIProviderEnrolmentDetailsRegister providerCreate apiProvDomIdand apiProvFuncIdsfor provided functionsProvider withapfId and aefIdsProvider withapfId and aefIdsalt[Publish Service]Publish serviceswith providerIdandServiceAPIDescriptionPublish servicesAre AEFs areregistered for provider?OkCreate apiIdInstall chartOptional and not decided yetOkalt[Subcribed Event Handling]Service publishedCAPIFEventDetailServiceAPIDescriptionwith apiIdServiceAPIDescriptionwith apiIdalt[Register Invoker]Register invoker withAPIInvokerEnrolmentDetailsRegister invokerCreate apiInvokerId andonboardingSecretGet available servicesAvailable servicesalt[Subcribed Event Handling]Invoker registeredCAPIFEventDetailServices availablefor the invokerInvoker with invokerIdand available servicesOkalt[Discover Services]Discover services for aninvoker with apiInvokerIdand filter parametersGet services availablefor the invokerGet services availablefor the invokerGet available servicesAvailable servicesServices availablefor the invokerServices available for theinvoker matching thefilter parametersServices available for theinvoker and matching thefilter parametersalt[Security Service]Request tokenfor service withAccessTokenReqIs invoker registered?OkIs secret valid?OkIs function providingservice registered?OkIs service published?OkAccessTokenRsp withtokenalt[Event Service]Subscribe to event with EventSubscriptionCreate subscriptionIdsubscriptionId