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.