CAPIF_Publish_Service_API

API for publishing service APIs.

OpenAPI

OpenAPI Version: 3.0.0

info

Title: CAPIF_Publish_Service_API

Description: This API enables the API publishing function to communicate with the CAPIF core function to publish the service API information and manage the published service API information.

Version: "1.0.0"

externalDocs

Description: 3GPP TS 29.222 V15.2.0 Common API Framework for 3GPP Northbound APIs

URL: http://www.3gpp.org/ftp/Specs/archive/29_series/29.222/

servers

URL: '{apiRoot}/published-apis/v1'

Variables:

API Root:

Default: https://example.com

Description: apiRoot as defined in subclause 7.5 of 3GPP TS 29.222.

paths

# APF published API

apfId and service-apis

Method: Post

Description: Publish a new API.

Parameters:

- name: apfId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/apfId'

Request Body:

Required/Optional: true

Content:

Application/JSON:

Schema:

Reference: '#/components/schemas/ServiceAPIDescription'

Responses:

'201' Service API published successfully The URI of the created resource shall be returned in the "Location" HTTP header.

Content:

Application/JSON:

Schema:

Reference: '#/components/schemas/ServiceAPIDescription'

Headers:

Location:

Description: 'Contains the URI of the newly created resource, according to the structure: {apiRoot}/published-apis/v1/{apfId}/service-apis/{serviceApiId}'

Required/Optional: true

Schema:

Type: string

'400': Reference 'TS29122_CommonData.yaml#/components/responses/400'

'401': Reference 'TS29122_CommonData.yaml#/components/responses/401'

'403': Reference 'TS29122_CommonData.yaml#/components/responses/403'

'404': Reference 'TS29122_CommonData.yaml#/components/responses/404'

'411': Reference 'TS29122_CommonData.yaml#/components/responses/411'

'413': Reference 'TS29122_CommonData.yaml#/components/responses/413'

'415': Reference 'TS29122_CommonData.yaml#/components/responses/415'

'429': Reference 'TS29122_CommonData.yaml#/components/responses/429'

'500': Reference 'TS29122_CommonData.yaml#/components/responses/500'

'503': Reference 'TS29122_CommonData.yaml#/components/responses/503'

default: Reference 'TS29122_CommonData.yaml#/components/responses/default'

get:

Description: Retrieve all published APIs.

Parameters:

- name: apfId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/apfId'

Responses:

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

Content:

Application/JSON:

Schema:

Reference: '#/components/schemas/ServiceAPIDescription'

'400': Reference 'TS29122_CommonData.yaml#/components/responses/400'

'401': Reference 'TS29122_CommonData.yaml#/components/responses/401'

'403': Reference 'TS29122_CommonData.yaml#/components/responses/403'

'404': Reference 'TS29122_CommonData.yaml#/components/responses/404'

'406': Reference 'TS29122_CommonData.yaml#/components/responses/406'

'429': Reference 'TS29122_CommonData.yaml#/components/responses/429'

'500': Reference 'TS29122_CommonData.yaml#/components/responses/500'

'503': Reference 'TS29122_CommonData.yaml#/components/responses/503'

default: Reference 'TS29122_CommonData.yaml#/components/responses/default'

# Individual APF published API

apfId, service-apis and serviceApiId

get:

Description: Retrieve a published service API.

Parameters:

- name: serviceApiId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/serviceApiId'

- name: apfId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/apfId'

Responses:

'200' Definition of all service API published by the API publishing function.

Content:

Application/JSON:

Schema:

Reference: '#/components/schemas/ServiceAPIDescription'

'400': Reference 'TS29122_CommonData.yaml#/components/responses/400'

'401': Reference 'TS29122_CommonData.yaml#/components/responses/401'

'403': Reference 'TS29122_CommonData.yaml#/components/responses/403'

'404': Reference 'TS29122_CommonData.yaml#/components/responses/404'

'406': Reference 'TS29122_CommonData.yaml#/components/responses/406'

'429': Reference 'TS29122_CommonData.yaml#/components/responses/429'

'500': Reference 'TS29122_CommonData.yaml#/components/responses/500'

'503': Reference 'TS29122_CommonData.yaml#/components/responses/503'

default: Reference 'TS29122_CommonData.yaml#/components/responses/default'

put:

Description: Update a published service API.

Parameters:

- name: serviceApiId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/serviceApiId'

- name: apfId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/apfId'

Request Body:

Required/Optional: true

Content:

Application/JSON:

Schema:

Reference: '#/components/schemas/ServiceAPIDescription'

Responses:

'200' Definition of service API updated successfully.

Content:

Application/JSON:

Schema:

Reference: '#/components/schemas/ServiceAPIDescription'

'400': Reference 'TS29122_CommonData.yaml#/components/responses/400'

'401': Reference 'TS29122_CommonData.yaml#/components/responses/401'

'403': Reference 'TS29122_CommonData.yaml#/components/responses/403'

'404': Reference 'TS29122_CommonData.yaml#/components/responses/404'

'411': Reference 'TS29122_CommonData.yaml#/components/responses/411'

'413': Reference 'TS29122_CommonData.yaml#/components/responses/413'

'415': Reference 'TS29122_CommonData.yaml#/components/responses/415'

'429': Reference 'TS29122_CommonData.yaml#/components/responses/429'

'500': Reference 'TS29122_CommonData.yaml#/components/responses/500'

'503': Reference 'TS29122_CommonData.yaml#/components/responses/503'

default: Reference 'TS29122_CommonData.yaml#/components/responses/default'

delete:

Description: Unpublish a published service API.

Parameters:

- name: serviceApiId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/serviceApiId'

- name: apfId

In: path

Required/Optional: true

Schema:

Reference: '#/components/schemas/apfId'

Responses:

'204' The individual published service API matching the serviceAPiId is deleted.

'400': Reference 'TS29122_CommonData.yaml#/components/responses/400'

'401': Reference 'TS29122_CommonData.yaml#/components/responses/401'

'403': Reference 'TS29122_CommonData.yaml#/components/responses/403'

'404': Reference 'TS29122_CommonData.yaml#/components/responses/404'

'429': Reference 'TS29122_CommonData.yaml#/components/responses/429'

'500': Reference 'TS29122_CommonData.yaml#/components/responses/500'

'503': Reference 'TS29122_CommonData.yaml#/components/responses/503'

default: Reference 'TS29122_CommonData.yaml#/components/responses/default'

# Components

components

schemas

# Data types uses as path variables

apfId

Type: string

Description: Identification of the API publishing function.

serviceApiId

Type: string

Description: String identifying an individual published service API.

# Data Type for representations

ServiceAPIDescription

Type: object

Properties:

apiName:

Type: string

Description: API name, it is set as {apiName} part of the URI structure as defined in subclause 4.4 of 3GPP TS 29.501.

apiId:

Type: string

Description: 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:

Type: array

Items:

Reference: '#/components/schemas/AefProfile'

minItems: 1

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

Type: string

Description: Text description of the API

supportedFeatures:

Reference: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

Required:

- apiName

InterfaceDescription

Type: object

Properties:

ipv4Addr:

Reference: 'TS29122_CommonData.yaml#/components/schemas/Ipv4Addr'

ipv6Addr:

Reference: 'TS29122_CommonData.yaml#/components/schemas/Ipv6Addr'

port:

Reference: 'TS29122_CommonData.yaml#/components/schemas/Port'

securityMethods:

Type: array

Items:

Reference: '#/components/schemas/SecurityMethod'

minItems: 1

Description: Security methods supported by the interface, it take precedence over the security methods provided in AefProfile, for this specific interface.

oneOf:

- required: [ipv4Addr]

- required: [ipv6Addr]

AefProfile

Type: object

Properties:

aefId:

Type: string

Description: Identifier of the API exposing function

versions:

Type: array

Items:

Reference: '#/components/schemas/Version'

minItems: 1

Description: API version

protocol:

Reference: '#/components/schemas/Protocol'

dataFormat:

Reference: '#/components/schemas/DataFormat'

securityMethods:

Type: array

Items:

Reference: '#/components/schemas/SecurityMethod'

minItems: 1

Description: Security methods supported by the AEF

domainName:

Type: string

Description: Domain to which API belongs to

interfaceDescriptions:

Type: array

Items:

Reference: '#/components/schemas/InterfaceDescription'

minItems: 1

Description: Interface details

Required:

- aefId

- versions

oneOf:

- required: [domainName]

- required: [interfaceDescriptions]

Resource

Type: object

Properties:

resourceName:

Type: string

Description: Resource name

commType:

Reference: '#/components/schemas/CommunicationType'

uri:

Type: string

Description: Relative URI of the API resource, it is set as {apiSpecificResourceUriPart} part of the URI structure as defined in subclause 4.4 of 3GPP TS 29.501.

custOpName:

Type: string

Description: it is set as {custOpName} part of the URI structure for a custom operation associated with a resource as defined in subclause 4.4 of 3GPP TS 29.501.

operations:

Type: array

Items:

Reference: '#/components/schemas/Operation'

minItems: 1

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

Type: string

Description: Text description of the API resource

Required:

- resourceName

- commType

- uri

CustomOperation

Type: object

Properties:

commType:

Reference: '#/components/schemas/CommunicationType'

custOpName:

Type: string

Description: it is set as {custOpName} part of the URI structure for a custom operation without resource association as defined in subclause 4.4 of 3GPP TS 29.501.

operations:

Type: array

Items:

Reference: '#/components/schemas/Operation'

minItems: 1

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

Type: string

Description: Text description of the custom operation

Required:

- commType

- custOpName

Version

Type: object

Properties:

apiVersion:

Type: string

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

expiry:

Reference: 'TS29571_CommonData.yaml#/components/schemas/DateTime'

resources:

Type: array

Items:

Reference: '#/components/schemas/Resource'

minItems: 1

Description: Resources supported by the API.

custOperations:

Type: array

Items:

Reference: '#/components/schemas/CustomOperation'

minItems: 1

Description: Custom operations without resource association.

Required:

- apiVersion

Protocol

anyOf:

- type: string

This string provides forward-compatibility with future

extensions to the enumeration but is not used to encode

content defined in the present version of this API.

Possible values are

- HTTP_1_1: HTTP version 1.1

- HTTP_2: HTTP version 2

CommunicationType

anyOf:

- type: string

This string provides forward-compatibility with future

extensions to the enumeration but is not used to encode

content defined in the present version of this API.

Possible values are

- REQUEST_RESPONSE: The communication is of the type request-response

- SUBSCRIBE_NOTIFY: The communication is of the type subscribe-notify

DataFormat

anyOf:

- type: string

This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

Possible values are

- JSON: JavaScript Object Notation

SecurityMethod

anyOf:

- type: string

This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

Possible values are

- PSK: Security method 1 (Using TLS-PSK) as described in 3GPP TS 33.122

- PKI: Security method 2 (Using PKI) as described in 3GPP TS 33.122

- OAUTH: Security method 3 (TLS with OAuth token) as described in 3GPP TS 33.122

Operation

anyOf:

- type: string

This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

Possible values are

- GET: HTTP GET method

- POST: HTTP POST method

- PUT: HTTP PUT method

- PATCH: HTTP PATCH method

- DELETE: HTTP DELETE method