8.4 CAPIF_API_Invoker_Management_API
29.2223GPPCommon API Framework for 3GPP Northbound APIsRelease 18TS
8.4.1 API URI
The CAPIF_API_Invoker_Management_API service shall use the CAPIF_API_Invoker_Management_API.
The request URIs used in HTTP requests from the API invoker towards the CAPIF core function shall have the Resource URI structure as defined in clause 7.5 with the following clarifications:
– The <apiName> shall be "api-invoker-management".
– The <apiVersion> shall be "v1".
– The <apiSpecificSuffixes> shall be set as described in clause 8.4.2.
8.4.2 Resources
8.4.2.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 8.4.2.1-1 depicts the resource URIs structure for the CAPIF_API_Invoker_Management_API.
Figure 8.4.2.1-1: Resource URI structure of the CAPIF_API_Invoker_Management_API
Table 8.4.2.1-1 provides an overview of the resources and applicable HTTP methods.
Table 8.4.2.1-1: Resources and methods overview
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
On-boarded API Invokers |
/onboardedInvokers (NOTE) |
POST |
On-boards a new API invoker by creating an API invoker profile |
Individual On-boarded API Invoker |
/onboardedInvokers/{onboardingId} (NOTE) |
DELETE |
Off-boards an individual API invoker by deleting the associated API invoker profile identified by {onboardingId} |
PATCH |
Modifies the API invoker details of an individual API invoker identified by the {onboardingId} |
||
PUT |
Updates the API invoker details of an individual API invoker identified by the {onboardingId} |
||
NOTE: The path segment "onboardedInvokers" does not follow the related naming convention defined in subclause 7.5.1. The path segment is however kept as currently defined in this specification for backward compatibility considerations. |
8.4.2.2 Resource: On-boarded API invokers
8.4.2.2.1 Description
The On-boarded API Invokers resource represents all the API invokers that are on-boarded at a given CAPIF core function.
8.4.2.2.2 Resource Definition
Resource URI: {apiRoot}/api-invoker-management/<apiVersion>/onboardedInvokers
This resource shall support the resource URI variables defined in table 8.4.2.2.2-1.
Table 8.4.2.2.2-1: Resource URI variables for this resource
Name |
Data Type |
Definition |
apiRoot |
string |
See clause 7.5 |
8.4.2.2.3 Resource Standard Methods
8.4.2.2.3.1 POST
This method shall support the URI query parameters specified in table 8.4.2.2.3.1-1.
Table 8.4.2.2.3.1-1: URI query parameters supported by the POST method on this resource
Name |
Data type |
P |
Cardinality |
Description |
n/a |
This method shall support the request data structures specified in table 8.4.2.2.3.1-2 and the response data structures and response codes specified in table 8.4.2.2.3.1-3.
Table 8.4.2.2.3.1-2: Data structures supported by the POST Request Body on this resource
Data type |
P |
Cardinality |
Description |
APIInvokerEnrolmentDetails |
M |
1 |
Enrolment details of the API invoker including notification destination URI for any on-boarding related notifications and an optional list of APIs the API invoker intends to invoke while on-board. |
Table 8.4.2.2.3.1-3: Data structures supported by the POST Response Body on this resource
Data type |
P |
Cardinality |
Response codes |
Description |
APIInvokerEnrolmentDetails |
M |
1 |
201 Created |
API invoker on-boarded successfully The URI of the created resource shall be returned in the "Location" HTTP header. A list of APIs the API invoker is allowed to invoke while on-board may also be included as part of the APIInvokerEnrolmentDetails which is provided in the response body, if requested in the POST request. |
n/a |
202 Accepted |
The CAPIF core has accepted the Onboarding request and is processing it. When processing is completed, the CAPIF core function will send a Notify_Onboarding_Completion notification to the requesting API invoker. See clause 8.4.3.2. |
||
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply. |
Table 8.4.2.2.3.1-4: Headers supported by the 201 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
Contains the URI of the newly created resource, according to the structure: {apiRoot}/api-invoker-management/<apiVersion>/onboardedInvokers/{onboardingId} |
8.4.2.2.4 Resource Custom Operations
None.
8.4.2.3 Resource: Individual On-boarded API Invoker
8.4.2.3.1 Description
The Individual On-boarded API Invokers resource represents an individual API invoker that is on-boarded at a given CAPIF core function.
8.4.2.3.2 Resource Definition
Resource URI: {apiRoot}/api-invoker-management/<apiVersion>/onboardedInvokers/{onboardingId}
This resource shall support the resource URI variables defined in table 8.4.2.3.2-1.
Table 8.4.2.3.2-1: Resource URI variables for this resource
Name |
Data Type |
Definition |
apiRoot |
string |
See clause 7.5 |
onboardingId |
string |
String identifying an individual on-boarded API invoker resource |
8.4.2.3.3 Resource Standard Methods
8.4.2.3.3.1 DELETE
This method shall support the URI query parameters specified in table 8.4.2.3.3.1-1.
Table 8.4.2.3.3.1-1: URI query parameters supported by the DELETE method on this resource
Name |
Data type |
P |
Cardinality |
Description |
n/a |
This method shall support the response codes specified in table 8.4.2.3.3.1-2 and the response data structures and response codes specified in table 8.4.2.3.3.1-3.
Table 8.4.2.3.3.1-2: Data structures supported by the DELETE Request Body on this resource
Data type |
P |
Cardinality |
Description |
n/a |
Table 8.4.2.3.3.1-3: Data structures supported by the DELETE Response Body on this resource
Data type |
P |
Cardinality |
Response codes |
Description |
n/a |
204 No Content |
The individual on-boarded API invoker matching the onboardingId is deleted |
||
n/a |
307 Temporary Redirect |
Temporary redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14]. |
||
n/a |
308 Permanent Redirect |
Permanent redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14]. |
||
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply. |
Table 8.4.2.3.3.1-4: Headers supported by the 307 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative CAPIF core function. |
Table 8.4.2.3.3.1-5: Headers supported by the 308 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative CAPIF core function. |
8.4.2.3.3.2 PUT
The PUT method allows updating the API invoker details of the onboarded API invoker. This method shall support the URI query parameters specified in table 8.4.2.3.3.2-1.
Table 8.4.2.3.3.2-1: URI query parameters supported by the PUT method on this resource
Name |
Data type |
P |
Cardinality |
Description |
n/a |
This method shall support the request data structures specified in the table 8.4.2.3.3.2-2 and the response data structures and response codes specified in the table 8.4.2.3.3.2-3.
Table 8.4.2.3.3.2-2: Data structures supported by the PUT Request Body on this resource
Data type |
P |
Cardinality |
Description |
APIInvokerEnrolmentDetails |
M |
1 |
Updated details of the API invoker and a notification destination URI for any update request related notifications. |
Table 8.4.2.3.3.2-3: Data structures supported by the PUT Response Body on this resource
Data type |
P |
Cardinality |
Response codes |
Description |
APIInvokerEnrolmentDetails |
M |
1 |
200 OK |
API invoker’s information updated successfully. Updated details of the API invoker as part of the APIInvokerEnrolmentDetails, which is provided in the response body. |
n/a |
202 Accepted |
The CAPIF core has accepted the Update details request and is processing it. When processing is completed, the CAPIF core function will send a Notify_Update_Completion notification to the requesting API invoker. See clause 8.4.3.3. |
||
n/a |
204 No Content |
API invoker’s information updated successfully, with no content to be sent in the response body. |
||
n/a |
307 Temporary Redirect |
Temporary redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14]. |
||
n/a |
308 Permanent Redirect |
Permanent redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14]. |
||
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply. |
Table 8.4.2.3.3.2-4: Headers supported by the 307 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative CAPIF core function. |
Table 8.4.2.3.3.2-5: Headers supported by the 308 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative CAPIF core function. |
8.4.2.3.3.3 PATCH
This method shall support the URI query parameters specified in table 8.4.2.3.3.3-1.
Table 8.4.2.3.3.3-1: URI query parameters supported by the PATCH method on this resource
Name |
Data type |
P |
Cardinality |
Description |
n/a |
This method shall support the request data structures specified in table 8.4.2.3.3.3-2 and the response data structures and response codes specified in table 8.4.2.3.3.3-3.
Table 8.4.2.3.3.3-2: Data structures supported by the PATCH Request Body on this resource
Data type |
P |
Cardinality |
Description |
APIInvokerEnrolmentDetailsPatch |
M |
1 |
Modified details of the API invoker and a notification destination URI for any modify request related notifications. |
Table 8.4.2.3.3.3-3: Data structures supported by the PATCH Response Body on this resource
Data type |
P |
Cardinality |
Response codes |
Description |
APIInvokerEnrolmentDetails |
M |
1 |
200 OK |
API invoker’s information modified successfully. Modified details of the API invoker as part of the APIInvokerEnrolmentDetails, which is provided in the response body. |
n/a |
202 Accepted |
The CAPIF core has accepted the modify details request and is processing it. When processing is completed, the CAPIF core function will send a Notify_Update_Completion notification to the requesting API invoker. See sub clause 8.4.3.3. |
||
n/a |
204 No Content |
API invoker’s information modified successfully, with no content to be sent in the response body. |
||
n/a |
307 Temporary Redirect |
Temporary redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14]. |
||
n/a |
308 Permanent Redirect |
Permanent redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14]. |
||
NOTE: The mandatory HTTP error status codes for the HTTP PATCH method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply. |
Table 8.4.2.3.3.3-4: Headers supported by the 307 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
String |
M |
1 |
An alternative URI of the resource located in an alternative CAPIF core function. |
Table 8.4.2.3.3.3-5: Headers supported by the 308 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
String |
M |
1 |
An alternative URI of the resource located in an alternative CAPIF core function. |
8.4.2.3.4 Resource Custom Operations
None.
8.4.3 Notifications
8.4.3.1 General
The delivery of notifications shall conform to clause 7.6.
Table 8.4.3.1-1: Notifications overview
Notification |
Callback URI |
HTTP method or custom operation |
Description (service operation) |
Notify_Onboarding_Completion |
{notificationDestination} |
POST |
Notify API invoker of on-boarding result |
Notify_Update_Completion |
{notificationDestination} |
POST |
Notify API invoker of update result details. |
8.4.3.2 Notify_Onboarding_Completion
8.4.3.2.1 Description
Notify_Onboarding_Completion is used by the CAPIF core function to notify an API invoker of the on-boarding result.
8.4.3.2.2 Notification definition
The POST method shall be used for Notify_Onboarding_Completion and the URI shall be the one provided by the API invoker during the on-boarding request.
Callback URI: {notificationDestination}
This method shall support the URI query parameters specified in table 8.4.3.2.2-1.
Table 8.4.3.2.2-1: URI query parameters supported by the POST method on this resource
Name |
Data type |
P |
Cardinality |
Description |
n/a |
This method shall support the request data structures specified in table 8.4.3.2.2-2 and the response data structures and response codes specified in table 8.4.3.2.2-3.
Table 8.4.3.2.2-2: Data structures supported by the POST Request Body on this resource
Data type |
P |
Cardinality |
Description |
OnboardingNotification |
M |
1 |
Notification with on-boarding result |
Table 8.4.3.2.2-3: Data structures supported by the POST Response Body on this resource
Data type |
P |
Cardinality |
Response codes |
Description |
n/a |
204 No Content |
The receipt of the Notification is acknowledged. |
||
n/a |
307 Temporary Redirect |
Temporary redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative notification destination where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
n/a |
308 Permanent Redirect |
Permanent redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative notification destination where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply. |
Table 8.4.3.2.2-4: Headers supported by the 307 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative notification destination towards which the notification should be redirected. |
Table 8.4.3.2.2-5: Headers supported by the 308 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative notification destination towards which the notification should be redirected. |
8.4.3.3 Notify_Update_Completion
8.4.3.3.1 Description
Notify_Update_Completion is used by the CAPIF core function to notify of the update of API Invoker’s details result.
8.4.3.3.2 Notification definition
The POST method shall be used for Notify_Update_Completion and the URI shall be the one provided by the API invoker during the API invoker details update request.
Callback URI: {notificationDestination}
This method shall support the URI query parameters specified in table 8.4.3.3.2-1.
Table 8.4.3.3.2-1: URI query parameters supported by the POST method on this resource
Name |
Data type |
P |
Cardinality |
Description |
n/a |
This method shall support the request data structures specified in table 8.4.3.3.2-2 and the response data structures and response codes specified in table 8.4.3.3.2-3.
Table 8.4.3.3.2-2: Data structures supported by the POST Request Body on this resource
Data type |
P |
Cardinality |
Description |
OnboardingNotification |
M |
1 |
Notification with API Invoker’s details update result. |
Table 8.4.3.3.2-3: Data structures supported by the POST Response Body on this resource
Data type |
P |
Cardinality |
Response codes |
Description |
n/a |
204 No Content |
The receipt of the Notification is acknowledged. |
||
n/a |
307 Temporary Redirect |
Temporary redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative notification destination where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
n/a |
308 Permanent Redirect |
Permanent redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative notification destination where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply. |
Table 8.4.3.3.2-4: Headers supported by the 307 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative notification destination towards which the notification should be redirected. |
Table 8.4.3.3.2-5: Headers supported by the 308 Response Code on this resource
Name |
Data type |
P |
Cardinality |
Description |
Location |
string |
M |
1 |
An alternative URI representing the end point of an alternative notification destination towards which the notification should be redirected. |
8.4.4 Data Model
8.4.4.1 General
This clause specifies the application data model supported by the API. Data types listed in clause 7.2 also apply to this API.
Table 8.4.4.1-1 specifies the data types defined specifically for the CAPIF_API_Invoker_Management_API service.
Table 8.4.4.1-1: CAPIF_API_Invoker_Management_API specific Data Types
Data type |
Section defined |
Description |
Applicability |
APIInvokerEnrolmentDetails |
Clause 8.4.4.2.2 |
Represents information about the API Invoker that requested to onboard. |
|
APIInvokerEnrolmentDetailsPatch |
Clause 8.4.4.2.8 |
Represents an API Invoker’s enrolment details to be updated. |
PatchUpdate |
APIList |
Clause 8.4.4.2.4 |
The list of service APIs that the API Invoker is allowed to invoke. |
|
OnboardingInformation |
Clause 8.4.4.2.5 |
Represents on-boarding information of the API invoker. |
|
OnboardingNotification |
Clause 8.4.4.2.7 |
Represents the notification with on-boarding or update result. |
Table 8.4.4.1-2 specifies data types re-used by the CAPIF_API_Invoker_Management_API service.
Table 8.4.4.1-2: Re-used Data Types
Data type |
Reference |
Comments |
Applicability |
SupportedFeatures |
3GPP TS 29.571 [19] |
Used to negotiate the applicability of optional features defined in table 8.4.6-1. |
8.4.4.2 Structured data types
8.4.4.2.1 Introduction
8.4.4.2.2 Type: APIInvokerEnrolmentDetails
Table 8.4.4.2.2-1: Definition of type APIInvokerEnrolmentDetails
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
apiInvokerId |
string |
O |
0..1 |
API invoker ID assigned by the CAPIF core function to the API invoker while on-boarding the API invoker. Shall not be present in the HTTP POST request from the API invoker to the CAPIF core function, to on-board itself. Shall be present in all other HTTP requests and responses. |
|
onboardingInformation |
OnboardingInformation |
M |
1 |
On-boarding information about the API invoker necessary for the CAPIF core function to on-board the API invoker. |
|
notificationDestination |
Uri |
M |
1 |
URI where the notification should be delivered to. |
|
requestTestNotification |
boolean |
O |
0..1 |
Set to true by Subscriber to request the CAPIF core function to send a test notification as defined in in clause 7.6. Set to false or omitted otherwise. |
Notification_test_event |
websockNotifConfig |
WebsockNotifConfig |
O |
0..1 |
Configuration parameters to set up notification delivery over Websocket protocol as defined in clause 7.6. |
Notification_websocket |
apiList |
APIList |
O |
0..1 |
A list of APIs. When included by the API invoker in the HTTP request message, it lists the APIs that the API invoker intends to invoke while onboard or API invoker update. When included by the CAPIF core function in the HTTP response message, it lists the APIs that the API invoker is allowed to invoke while onboard or API invoker update. |
|
apiInvokerInformation |
string |
O |
0..1 |
Generic information related to the API invoker such as details of the device or the application. |
|
supportedFeatures |
SupportedFeatures |
O |
0..1 |
Used to negotiate the supported optional features of the API as described in clause 7.8. This attribute shall be provided in the HTTP POST request and in the response of successful resource creation. |
8.4.4.2.3 Type: Void
8.4.4.2.4 Type: APIList
Table 8.4.4.2.4-1: Definition of type APIList
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
serviceAPIDescriptions |
array(ServiceAPIDescription) |
O |
1..N |
Definition of the service API. |
8.4.4.2.5 Type: OnboardingInformation
Table 8.4.4.2.5-1: Definition of type OnboardingInformation
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
apiInvokerPublicKey |
string |
M |
1 |
Public Key of API Invoker |
|
apiInvokerCertificate |
string |
O |
0..1 |
API invoker’s generic client certificate. The subject field in the certificate shall be encoded with API invoker ID as Common Name as specified in IETF RFC 5280 [29]. |
|
onboardingSecret |
string |
O |
0..1 |
API invoker’s onboarding secret, provided by the CAPIF core function. |
8.4.4.2.6 Type: Void
8.4.4.2.7 Type: OnboardingNotification
Table 8.4.4.2.7-1: Definition of type OnboardingNotification
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
result |
boolean |
M |
1 |
Set to "true" indicate successful on-boarding. Otherwise set to "false" |
|
resourceLocation |
Uri |
C |
1 |
URI pointing to the new CAPIF resource created as a result of successful on-boarding. This attribute shall be present if ‘result’ attribute is set to "true". Otherwise it shall not be present. |
|
apiInvokerEnrolmentDetails |
APIInvokerEnrolmentDetails |
C |
1 |
Enrolment details of the API invoker which are verified by the CAPIF administrator or API management. This attribute shall be present if ‘result’ attribute is set to "true". Otherwise it shall not be present. |
|
apiList |
APIList |
O |
0..1 |
List of APIs API invoker is allowed to access. This attribute may be present if ‘result’ attribute is set to "true". Otherwise it shall not be present. |
8.4.4.2.8 Type: APIInvokerEnrolmentDetailsPatch
Table 8.4.4.2.8-1: Definition of type APIInvokerEnrolmentDetailsPatch
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
onboardingInformation |
OnboardingInformation |
O |
1 |
On-boarding information about the API invoker necessary for the CAPIF core function to on-board the API invoker. |
|
notificationDestination |
Uri |
O |
1 |
URI where the notification should be delivered to. |
|
apiList |
APIList |
O |
0..1 |
A list of APIs. When included by the API invoker in the HTTP request message, it lists the APIs that the API invoker intends to invoke while onboard or API invoker update. |
|
apiInvokerInformation |
string |
O |
0..1 |
Generic information related to the API invoker such as details of the device or the application. |
8.4.4.3 Simple data types and enumerations
None.
8.4.5 Error Handling
8.4.5.1 General
HTTP error handling shall be supported as specified in clause 7.7.
In addition, the requirements in the following clauses shall apply.
8.4.5.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the CAPIF_API_Invoker_Management_API.
8.4.5.3 Application Errors
The application errors defined for the CAPIF_API_Invoker_Management_API are listed in table 8.4.5.3-1.
Table 8.4.5.3-1: Application errors
Application Error |
HTTP status code |
Description |
Applicability |
8.4.6 Feature negotiation
General feature negotiation procedures are defined in clause 7.8. Table 8.4.6-1 lists the supported features for CAPIF_API_Invoker_Management_API.
Table 8.4.6-1: Supported Features
Feature number |
Feature Name |
Description |
1 |
Notification_test_event |
Testing of notification connection is supported according to clause 7.6. |
2 |
Notification_websocket |
The delivery of notifications over Websocket is supported according to clause 7.6. This feature requires that the Notification_test_event feature is also supported. |
3 |
PatchUpdate |
Indicates the support of the PATCH method for updating an On-boarded API Invoker resource. |