openapi: 3.0.0

info:
  title: CAPIF_Discover_Service_API
  description: |
    API for discovering service APIs.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.
  version: "1.4.0"

externalDocs:
  description: 3GPP TS 29.222 V19.5.0 Common API Framework for 3GPP Northbound APIs
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.222/

servers:
  - url: '{apiRoot}/service-apis/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 7.5 of 3GPP TS 29.222.

paths:
  /allServiceAPIs:
    get:
      description: >
        Discover published service APIs and retrieve a collection of APIs according
        to certain filter criteria.
      operationId: GetPubServAPIs
      tags:
        - All published service APIs (Collection)
      parameters:
        - name: api-invoker-id
          in: query
          description: >
             String identifying the API invoker assigned by the CAPIF core function.
             It also represents the CCF identifier in the CAPIF-6/6e interface.
          required: true
          schema:
            type: string
        - name: api-name
          in: query
          description: >
            Contains the API name set to the value of the "<apiName>" placeholder of the API URI as
            defined in clause 5.2.4 of 3GPP TS 29.122 [14].
          schema:
            type: string
        - name: api-version
          in: query
          description: API major version the URI (e.g. v1).
          schema:
            type: string
        - name: comm-type
          in: query
          description: Communication type used by the API (e.g. REQUEST_RESPONSE).
          schema:
            $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/CommunicationType'
        - name: protocol
          in: query
          description: Protocol used by the API.
          schema:
            $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/Protocol'
        - name: aef-id
          in: query
          description: AEF identifer.
          schema:
            type: string
        - name: data-format
          in: query
          description: Data formats used by the API (e.g. serialization protocol JSON used).
          schema:
            $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/DataFormat'
        - name: api-cat
          in: query
          description: The service API category to which the service API belongs to.
          schema:
            type: string
        - name: preferred-aef-loc
          in: query
          description: The preferred AEF location.
          content:
            application/json:
              schema:
                $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/AefLocation'
        - name: req-api-prov-name
          in: query
          description: Represents the required API provider name.
          schema:
            type: string
        - name: api-supported-features
          in: query
          description: >
            Features supported by the discovered service API indicated by api-name parameter.
            This may only be present if api-name query parameter is present.
          schema:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
        - name: ue-ip-addr
          in: query
          description: Represents the UE IP address information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddrInfo'
        - name: service-kpis
          in: query
          description: >
            Contains iInformation about service characteristics provided by the targeted 
            service API(s).
          content:
            application/json:
              schema:
                $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/ServiceKpis'
        - name: net-slice-info
          in: query
          description: >
            Contains the identifier(s) of the network slice(s) within which the API
            shall be available.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'TS29435_NSCE_PolicyManagement.yaml#/components/schemas/NetSliceId'
                minItems: 1
        - name: grant-types
          in: query
          description: Contains the OAuth grant types that need to be supported.
          required: false
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'TS29222_CAPIF_Security_API.yaml#/components/schemas/OAuthGrantType'
                minItems: 1
        - name: api-ids
          in: query
          description: >
            Contains the identifier(s) of the targeted service APIs.
            When this query parameter is present, then all the other query parameters shall be
            absent except the supported-features and api-invoker-id query parameters.
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            minItems: 1
        - name: res-ops
          in: query
          description: >
            Contains the list of supported API resource(s) and service operation(s).
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ResOperInfo'
            minItems: 1
        - name: supported-features
          in: query
          description: Features supported by the NF consumer for the CAPIF Discover Service API.
          schema:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      responses:
        '200':
          description: >
            The response body contains the result of the search over the list of registered APIs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveredAPIs'
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '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'
        '414':
          $ref: 'TS29122_CommonData.yaml#/components/responses/414'
        '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:
  schemas:
    DiscoveredAPIs:
      type: object
      description: >
        Represents a list of APIs currently registered in the CAPIF core function
        and satisfying a number of filter criteria provided by the API consumer.
      properties:
        serviceAPIDescriptions:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/ServiceAPIDescription'
          minItems: 1
          description: >
            Description of the service API as published by the service. Each service
            API information shall include AEF profiles matching the filter criteria.
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

    IpAddrInfo:
      type: object
      description: Represents the UE IP address information.
      properties:
        ipv4Addr:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv4Addr'
        ipv6Addr:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv6Addr'
      oneOf:
        - required: [ipv4Addr]
        - required: [ipv6Addr] 

    ResOperInfo:
      type: object
      description: >
        Represents the resourse and/or service operation.
      properties:
        resource:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        operations:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/Operation'
          minItems: 1
        customServOpers:
          type: array
          items:
            type: string
          minItems: 1