Upload New File

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

      apiRoot:

        default: https://example.com

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

paths:

# APF published API

  /{apfId}/service-apis:

    post:

      description: Publish a new API.

      parameters:

        - name: apfId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/apfId'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/ServiceAPIDescription'

      responses:

        '201':

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

          content:

            application/json:

              schema:

                $ref: '#/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: true

              schema:

                type: string

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '411':

          $ref: 'TS29122_CommonData.yaml#/components/responses/411'

        '413':

          $ref: 'TS29122_CommonData.yaml#/components/responses/413'

        '415':

          $ref: 'TS29122_CommonData.yaml#/components/responses/415'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    get:

      description: Retrieve all published APIs.

      parameters:

        - name: apfId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/apfId'

      responses:

        '200':

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

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ServiceAPIDescription'

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '406':

          $ref: 'TS29122_CommonData.yaml#/components/responses/406'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

# Individual APF published API

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

    get:

      description: Retrieve a published service API.

      parameters:

        - name: serviceApiId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/serviceApiId'

        - name: apfId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/apfId'

      responses:

        '200':

          description: Definition of all service API published by the API publishing function.

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ServiceAPIDescription'

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '406':

          $ref: 'TS29122_CommonData.yaml#/components/responses/406'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    put:

      description: Update a published service API.

      parameters:

        - name: serviceApiId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/serviceApiId'

        - name: apfId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/apfId'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/ServiceAPIDescription'

      responses:

        '200':

          description: Definition of service API updated successfully.

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ServiceAPIDescription'

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '411':

          $ref: 'TS29122_CommonData.yaml#/components/responses/411'

        '413':

          $ref: 'TS29122_CommonData.yaml#/components/responses/413'

        '415':

          $ref: 'TS29122_CommonData.yaml#/components/responses/415'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    delete:

      description: Unpublish a published service API.

      parameters:

        - name: serviceApiId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/serviceApiId'

        - name: apfId

          in: path

          required: true

          schema:

            $ref: '#/components/schemas/apfId'

      responses:

        '204':

          description: The individual published service API matching the serviceAPiId is deleted.

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: '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:

            $ref: '#/components/schemas/AefProfile'

          minItems: 1

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

        description:

          type: string

          description: Text description of the API

        supportedFeatures:

          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

      required:

        - apiName

    InterfaceDescription:

      type: object

      properties:

        ipv4Addr:

          $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv4Addr'

        ipv6Addr:

          $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv6Addr'

        port:

          $ref: 'TS29122_CommonData.yaml#/components/schemas/Port'

        securityMethods:

          type: array

          items:

            $ref: '#/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:

            $ref: '#/components/schemas/Version'

          minItems: 1

          description: API version

        protocol:

          $ref: '#/components/schemas/Protocol'

        dataFormat:

          $ref: '#/components/schemas/DataFormat'

        securityMethods:

          type: array

          items:

            $ref: '#/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:

            $ref: '#/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:

          $ref: '#/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:

            $ref: '#/components/schemas/Operation'

          minItems: 1

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

        description:

          type: string

          description: Text description of the API resource

      required:

        - resourceName

        - commType

        - uri

    CustomOperation:

      type: object

      properties:

        commType:

          $ref: '#/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:

            $ref: '#/components/schemas/Operation'

          minItems: 1

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

        description:

          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:

          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'

        resources:

          type: array

          items:

            $ref: '#/components/schemas/Resource'

          minItems: 1

          description: Resources supported by the API.

        custOperations:

          type: array

          items:

            $ref: '#/components/schemas/CustomOperation'

          minItems: 1

          description: Custom operations without resource association.

      required:

        - apiVersion

    Protocol:

      anyOf:

      - type: string

        enum:

          - HTTP_1_1

          - HTTP_2

      - type: string

        description: >

          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.

      description: >

        Possible values are

        - HTTP_1_1: HTTP version 1.1

        - HTTP_2: HTTP version 2

    CommunicationType:

      anyOf:

      - type: string

        enum:

          - REQUEST_RESPONSE

          - SUBSCRIBE_NOTIFY

      - type: string

        description: >

          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.

      description: >

        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

        enum:

          - JSON

      - type: string

        description: >

          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.

      description: >

        Possible values are

        - JSON: JavaScript Object Notation

    SecurityMethod:

      anyOf:

      - type: string

        enum:

          - PSK

          - PKI

          - OAUTH

      - type: string

        description: >

          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.

      description: >

        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

        enum:

          - GET

          - POST

          - PUT

          - PATCH

          - DELETE

      - type: string

        description: >

          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.

      description: >

        Possible values are

        - GET: HTTP GET method

        - POST: HTTP POST method

        - PUT: HTTP PUT method

        - PATCH: HTTP PATCH method

        - DELETE: HTTP DELETE method