TS29222_CAPIF_Publish_Service_API.yaml

openapi: 3.0.0
info:
  title: CAPIF_Publish_Service_API
  description: |
    API for publishing service APIs.
    © 2020, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.
  version: "1.1.0.alpha-2"
externalDocs:
  description: 3GPP TS 29.222 V16.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'
        shareableInfo:
          $ref: '#/components/schemas/ShareableInformation'
        serviceAPICategory:
          type: string
        apiSuppFeats:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
        pubApiPath:
          $ref: '#/components/schemas/PublishedApiPath'
      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
    ShareableInformation:
      type: object
      properties:
        isShareable:
          type: boolean
        ccfProviderDomains:
          type: array
          items:
            type: string
          minItems: 1
      required:
        - isShareable
    PublishedApiPath:
      type: object
      properties:
        ccfIds:
          type: array
          items:
            type: string
          minItems: 1
          description: A list of CCF identifiers where the service API is already published.
    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