APF published APIs

/{apfId}/service-apis

POST

Publish a new API

GET

Retrieve all published service APIs

Individual APF published API

/{apfId}/service-apis/{serviceApiId}

GET

Retrieve a published service API

PUT

Update a published service API

PATCH

Modify a published service API.

DELETE

Unpublish a published service API.

apiRoot

string

See clause 7.5

apfId

string

Identifies the API publishing function; for CAPIF interconnection case, this string also identifies the CCF which is publishing the service API.

n/a

ServiceAPIDescription

M

1

Definition of the service API being published

ServiceAPIDescription

M

1

201 Created

Service API published successfully.

The URI of the created resource shall be returned in the "Location" HTTP header

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.

Location

string

M

1

Contains the URI of the newly created resource, according to the structure: {apiRoot}/published-apis/<apiVersion>/{apfId}/service-apis/{serviceApiId}

n/a

n/a

array(ServiceAPIDescription)

O

0..N

200 OK

Definition of all service API(s) published by the API publishing function.

n/a

307 Temporary Redirect

Temporary redirection, during resource retrieval. 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 retrieval. 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 GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

apiRoot

string

See clause 7.5

apfId

string

Identifies the API publishing function

serviceApiId

string

Identifies an individual published service API

n/a

n/a

ServiceAPIDescription

M

1

200 OK

Definition of individual service API published by the API publishing function.

n/a

307 Temporary Redirect

Temporary redirection, during resource retrieval. 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 retrieval. 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 GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

n/a

ServiceAPIDescription

M

1

Updated definition of the service API.

ServiceAPIDescription

M

1

200 OK

Definition of the service API updated successfully and the updated service API definition is returned.

n/a

204 No Content

Definition of the service API updated successfully.

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.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

n/a

n/a

n/a

204 No Content

The individual published service API matching the serviceApiId 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.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

n/a

ServiceAPIDescriptionPatch

M

1

Contains the modifications to be applied to the concerned Individual APF published API resource.

ServiceAPIDescription

M

1

200 OK

The definition of the service API is updated successfully and a representation of the modified service API definition is returned.

n/a

204 No Content

The definition of the service API is updated successfully.

n/a

307 Temporary Redirect

Temporary redirection. 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. 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.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

AefLocation

Clause 8.2.4.2.10

Represents the location information (e.g. civic address, GPS coordinates, data center ID) where the AEF providing the service API is located.

AefProfile

Clause 8.2.4.2.4

Represents the AEF profile data.

CommunicationType

Clause 8.2.4.3.5

Indicates a communication type of the resource or a custom operation.

CustomOperation

Clause 8.2.4.2.7

Represents the description of a custom operation.

DataFormat

Clause 8.2.4.3.4

Indicates a data format, e.g., JSON.

InterfaceDescription

Clause 8.2.4.2.3

Represents the description of the API interface.

Operation

Clause 8.2.4.3.7

Indicates an HTTP method (e.g. PUT).

Protocol

Clause 8.2.4.3.3

Indicates a protocol and protocol version used by the API.

PublishedApiPath

Clause 8.2.4.2.9

Represents the published API path within the same CAPIF provider domain.

Resource

Clause 8.2.4.2.6

Represents the API resource data.

SecurityMethod

Clause 8.2.4.3.6

Indicates the security method (e.g. PKI).

ServiceAPIDescription

Clause 8.2.4.2.2

Represents the description of a service API as published by the APF.

ServiceAPIDescriptionPatch

Clause 8.2.4.2.11

Represents the parameters to request the modification of an APF published API resource.

PatchUpdate

ShareableInformation

Clause 8.2.4.2.8

Indicates whether the service API and/or the service API category can be shared to the list of CAPIF provider domains.

Version

Clause 8.2.4.2.5

Represents the API version information

CivicAddress

3GPP TS 29.572 [30]

Used to indicate a civic address.

DateTime

3GPP TS 29.122 [14]

Used to indicate an expiration timer.

Fqdn

3GPP TS 29.571 [19]

GeographicArea

3GPP TS 29.572 [30]

Used to indicate a geographic area.

Ipv4Addr

3GPP TS 29.122 [14]

Used to indicate an IPv4 address.

Ipv6Addr

3GPP TS 29.122 [14]

Used to indicate an IPv6 address.

Port

3GPP TS 29.122 [14]

Used to indicate a port.

SupportedFeatures

3GPP TS 29.571 [19]

Used to negotiate the applicability of optional features defined in table 8.2.6-1.

ApiSupportedFeaturePublishing

apiName

string

M

1

API name, it is set as {apiName} part of the URI structure as defined in clause 5.2.4 of 3GPP TS 29.122 [14].

apiId

string

O

0..1

API identifier assigned by the CAPIF core function to the published service API. Shall not be present in the HTTP POST request from the API publishing function to the CAPIF core function. Shall be present in the HTTP POST response from the CAPIF core function to the API publishing function and in the HTTP GET response from the CAPIF core function to the API invoker (discovery API).

aefProfiles

array(AefProfile)

C

1..N

AEF profile information, which includes the exposed API details (e.g. protocol). For CAPIF-4/4e interface, API publishing function shall provide this attribute to the CAPIF core function in service API publishing. For CAPIF-1/1e interface, the CAPIF core function shall provide this attribute to the API Invoker during service API discovery. (NOTE 2)

description

string

O

0..1

Text description of the API

supportedFeatures

SupportedFeatures

O

0..1

The supported optional features of the CAPIF API. (NOTE 1)

shareableInfo

ShareableInformation

O

0..1

Represents whether the service API and/or the service API category can be published to other CCFs.

serviceAPICategory

string

C

0..1

The service API category to which the service API belongs to. This attribute is only applicable for CAPIF-6/6e interface. (NOTE 2)

ccfId

string

C

0..1

CAPIF core function identifier which can be contacted further for discovering the details of service API information. This attribute is only applicable for CAPIF-6/6e interface and shall be provided with serviceAPICategory. (NOTE 2)

apiSuppFeats

SupportedFeatures

O

0..1

Provided by the consumer to indicate the features supported by the service API.

ApiSupportedFeaturePublishing

pubApiPath

PublishedApiPath

C

0..1

It contains the published API path within the same CAPIF provider domain. it shall be provided by the CCF when publishing the service API to other CCF via the CAPIF-6 reference point.

NOTE 1: For CAPIF_Publish_Service_API, the supported features attribute shall be provided in the HTTP POST request and in the response of successful resource creation. In addition, the supportedFeatures attribute may include one or more the supported features as defined in clause 8.2.6.

NOTE 2: For CAPIF-6/6e interface, at least one of aefProfiles or serviceAPICategory and the corresponding ccfId shall be provided.

ipv4Addr

Ipv4Addr

C

0..1

String identifying an IPv4 address (NOTE 1)

ipv6Addr

Ipv6Addr

C

0..1

String identifying an IPv6 address (NOTE 1)

fqdn

Fqdn

C

0..1

String containing a Fully Qualified Domain Name. (NOTE 1)

ExtendedIntfDesc

port

Port

O

0..1

Port

apiPrefix

string

O

0..1

A string representing an optional deployment-specific string (API prefix) in the form of a sequence of path segments that starts with a "/" character.

ExtendedIntfDesc

securityMethods

array(SecurityMethod)

M

1..N

Security methods supported by the interface. It takes precedence over the security methods provided in AefProfile, for this specific interface

NOTE 1: Exactly one of the attributes "ipv4Addr", "ipv6Addr" and "fqdn" shall be included.

NOTE 2: When the contents of this data type are used to construct the apiRoot of an API, they are used as described in clause 4.4.1 of 3GPP TS 29.501 [18].

aefId

string

M

1

AEF identifier

versions

array(Version)

M

1..N

API version

protocol

Protocol

O

0..1

Protocol used by the API.

dataFormat

DataFormat

O

0..1

Data format used by the API

securityMethods

array(SecurityMethod)

O

1..N

Security methods supported by the AEF for all interfaces. Certain interfaces may have different security methods supported in the attribute interfaceDescriptions.

domainName

string

O

0..1

Domain to which API belongs to

(NOTE 1)

interfaceDescriptions

array(InterfaceDescription)

O

1..N

Interface details

(NOTE 1)

aefLocation

AefLocation

O

0..1

The location information (e.g. civic address, GPS coordinates, data center ID) where the AEF providing the service API is located.

NOTE 1: Only one of the attributes "domainName" or "interfaceDescriptions" shall be included.

NOTE 2: Notification or callback type of resource is not included.

apiVersion

string

M

1

API major version in URI (e.g. v1)

expiry

DateTime

O

0..1

Expiry date and time of the AEF service. This represents the planned retirement date as specified in clause 4.3.1.5 of 3GPP TS 29.501 [18].

resources

array(Resource)

O

1..N

Resources supported by the API. It may include the custom operations with resource association.

custOperations

array(CustomOperation)

O

1..N

Custom operations without resource association.

resourceName

string

M

1

Resource name.

commType

CommunicationType

M

1

Communication type used by the API resource. (NOTE 1)

uri

string

M

1

Relative URI of the API resource, it is set as {apiSpecificSuffixes} part of the URI structure as defined in clause 5.2.4 of 3GPP TS 29.122 [14].

custOpName

string

O

0..1

it is set as {custOpName} part of the URI structure for the case where there is only a single custom operation associated with this resource as defined in clause 5.2.4 of 3GPP TS 29.122 [14]. (NOTE 2)

custOperations

array(CustomOperation)

O

1..N

List of custom operations associated to this resource. (NOTE 2)

MultipleCustomOperations

operations

array(Operation)

C

1..N

Supported HTTP methods for the API resource. Only applicable when the protocol in AefProfile indicates HTTP.

description

string

O

0..1

Text description of the API resource.

NOTE 1: The communication type refers to the semantics of the resource or custom operation and is independent of the HTTP methods that are supported (e.g. if a resource is used for subscriptions then its CommunicationType shall be SUBSCRIBE_NOTIFY even if it supports also the GET method for retrieving the subscriptions).

NOTE 2: The attributes "custOpName" and "custOperations" are mutually exclusive.

commType

CommunicationType

M

1

Communication type used by the custom operation.

custOpName

string

M

1

it is set as {custOpName} part of the URI structure for a custom operation without resource association as defined in clause 5.2.4 of 3GPP TS 29.122 [14].

operations

array(Operation)

C

1..N

Supported HTTP methods for the custom operation. Only applicable when the protocol in AefProfile indicates HTTP.

description

string

O

0..1

Text description of the custom operation.

isShareable

boolean

M

1

Set to "true" indicates that the service API and/or the service API category can be shared to the list of CAPIF provider domain information. Otherwise set to "false".

capifProvDoms

array(string)

O

1..N

List of CAPIF provider domains to which the service API information to be shared. (NOTE)

NOTE: Only one CAPIF provider domain information shall be provided via the CAPIF-6e interface.

ccfIds

array(string)

O

1..N

A list of CCF identifiers where the service API is already published.

civicAddr

CivicAddress

O

0..1

Identifies the civic address where the AEF providing the service API is located. (NOTE)

geoArea

GeographicArea

O

0..1

Identifies the geographic area where the AEF providing the service API is located. (NOTE)

dcId

string

O

0..1

Identifies the data center where the AEF providing the service API is located. (NOTE)

NOTE: At least one of the attributes shall be included.

aefProfiles

array(AefProfile)

O

1..N

AEF profile information, which includes the exposed API details (e.g. protocol).

description

string

O

0..1

Text description of the API

shareableInfo

ShareableInformation

O

0..1

Represents whether the service API and/or the service API category can be published to other CCFs.

serviceAPICategory

string

O

0..1

The service API category to which the service API belongs. This attribute is only applicable for CAPIF-6/6e interface.

(NOTE)

ccfId

string

O

0..1

CAPIF core function identifier which can be contacted further for discovering the details of service API information. This attribute is only applicable for CAPIF-6/6e interface and shall be provided if the "serviceAPICategory" attribute is provided.

(NOTE)

apiSuppFeats

SupportedFeatures

O

0..1

Indicates the features supported by the service API.

ApiSupportedFeaturePublishing

pubApiPath

PublishedApiPath

O

0..1

It contains the published API path within the same CAPIF provider domain. It is applicable only for the CAPIF-6 reference point.

NOTE: For CAPIF-6/6e interface, either the "aefProfiles" attribute or the "serviceAPICategory" attribute and the corresponding "ccfId" attribute may be provided.

n/a

HTTP_1_1

HTTP version 1.1

HTTP_2

HTTP version 2

JSON

Serialization protocol: JavaScript Object Notation

REQUEST_RESPONSE

The communication is of the type request-response.

SUBSCRIBE_NOTIFY

The communication is of the type subscribe-notify

PSK

Security method 1 (Using TLS-PSK) as described in 3GPP TS 33.122 [16].

PKI

Security method 2 (Using PKI) as described in 3GPP TS 33.122 [16].

OAUTH

Security method 3 (TLS with OAuth token) as described in 3GPP TS 33.122 [16].

GET

HTTP GET method

POST

HTTP POST method

PUT

HTTP PUT method

PATCH

HTTP PATCH method

DELETE

HTTP DELETE method

1

ApiSupportedFeaturePublishing

Indicates the support of publishing with supported feature for a service API.

2

PatchUpdate

Indicates the support of the PATCH method for updating an APF published API resource.

3

ExtendedIntfDesc

Indicates the support of extended interface descriptions.

4

MultipleCustomOperations

Indicates the support of modelling multiple custom operations associated with a resource.