openapi: 3.0.0

info:
  version: '1.0.0-alpha.4'
  title: 'Neasdf_DNSContext'
  description: |
    EASDF DNS Context Service.
    © 2021, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.

externalDocs:
  description: 3GPP TS 29.556 V0.4.0; 5G System; Edge Application Server Discovery Services; Stage3
  url: http://www.3gpp.org/ftp/Specs/archive/29_series/29.556/

servers:
  - url: '{apiRoot}/neasdf-dnscontext/v1'
    variables:
      apiRoot:
        default: https://example.com
        description:  apiRoot as defined in clause 4.4 of 3GPP TS 29.501.

security:
  - {}
  - oAuth2ClientCredentials:
    - neasdf-dnscontext

paths:

  /dns-contexts:
    post:
      summary:  Create
      tags:
        - DNS contexts collection
      operationId: CreateDnsContext
      requestBody:
        description: representation of the DNS context to be created in the EASDF
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DnsContextCreateData'
      callbacks:
        dnsContextNotification:
          '{$request.body#/notifyUri}':
            post:
              requestBody:  # contents of the DNS context Notify request
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/DnsContextNotification'
              responses:
                '204':
                  description: successful notification
                '307':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/307'
                '308':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/308'
                '400':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/400'
                '403':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/403'
                '404':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/404'
                '411':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/411'
                '413':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/413'
                '415':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/415'
                '429':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/429'
                '500':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/500'
                '503':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/503'
                default:
                  $ref: 'TS29571_CommonData.yaml#/components/responses/default'

      responses:
        '201':
          description: successful creation of a DNS context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DnsContextCreatedData'
          headers:
            Location:
              description: 'Contains the URI of the newly created resource, according to the structure: {apiRoot}/neasdf-dnscontext/<apiVersion>/dns-contexts/{dnsContextId}'
              required: true
              schema:
                type: string
        '307':
          $ref: 'TS29571_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29571_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'

  /dns-contexts/{dnsContextId}:
    delete:
      summary:  Delete the DNS Context
      tags:
        - Individual DNS context
      operationId: DeleteDnsContext
      parameters:
        - name: dnsContextId
          in: path
          description:  DNS context Identifier
          required: true
          schema:
            type: string
      responses:
        '204':
          description: successful deletion of an SM context
        '307':
          $ref: 'TS29571_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29571_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'

    patch:
      summary: Updates the DNS context
      operationId: UpdateDnsContext
      tags:
        - Individual DNS context
      parameters:
        - name: dnsContextId
          in: path
          description:  DNS context Identifier
          required: true
          schema:
            type: string
        - name: Content-Encoding
          in: header
          description: Content-Encoding, described in IETF RFC 7231
          schema:
            type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: 'TS29571_CommonData.yaml#/components/schemas/PatchItem'
        required: true
      responses:
        '204':
          description: Successful update of the DNS context
          headers:
            Accept-Encoding:
              description: Accept-Encoding, described in IETF RFC 7694
              schema:
                type: string
        '307':
          $ref: 'TS29571_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29571_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '501':
          $ref: 'TS29571_CommonData.yaml#/components/responses/501'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'

    put:
      summary: Updates the DNS context (complete replacement)
      operationId: ReplaceDnsContext
      tags:
        - Individual DNS context
      parameters:
        - name: dnsContextId
          in: path
          description:  DNS context Identifier
          required: true
          schema:
            type: string
        - name: Content-Encoding
          in: header
          description: Content-Encoding, described in IETF RFC 7231
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DnsContextCreateData'
      responses:
        '204':
          description: Successful update of the DNS context
          headers:
            Accept-Encoding:
              description: Accept-Encoding, described in IETF RFC 7694
              schema:
                type: string
        '307':
          $ref: 'TS29571_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29571_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '501':
          $ref: 'TS29571_CommonData.yaml#/components/responses/501'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'


components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{nrfApiRoot}/oauth2/token'
          scopes:
            neasdf-dnscontext: Access to the neasdf-dnscontext API


  schemas:
#
# STRUCTURED DATA TYPES
#
    DnsContextCreateData:
      description: Data within Create request 
      type: object
      properties:
        ueIpv4Addr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv4Addr'
        ipv6Addr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv6Addr'
        dnn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnn'
        dnsRules:
          description: map of DNS message handling rules where a valid JSON string serves as key
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DnsRule'
          minProperties: 1
        notifyUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - dnn
      anyOf:
        - required: [ ueIpv4Addr ]
        - required: [ ipv6Addr ]

    DnsContextCreatedData:
      description: Data within Create response 
      type: object
      properties:      
        easdfIpv4Addr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv4Addr'
        easdfIpv6Addr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv6Addr'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      anyOf:
        - required: [ easdfIpv4Addr ]
        - required: [ easdfIpv6Addr ]

    DnsRule:
      description: DNS message handling rule 
      type: object
      properties:
        dnsRuleId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uint32'
        precedence:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uint32'
        dnsQueryMdtList:
          description: map of DNS query message detection templates where a valid JSON string serves as key
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DnsQueryMdt'
          minProperties: 1
        dnsRspMdtList:
          description: map of DNS response message detection templates where a valid JSON string serves as key
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DnsRspMdt'
          minProperties: 1
        dnsBasePatternList:
          description: map of references to DNS base patterns where a valid JSON string serves as key
          type: object
          additionalProperties:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
          minProperties: 1
        actionList:
          description: map of actions where a valid JSON string serves as key
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Action'
          minProperties: 1
      required:
        - dnsRuleId
        - precedence
        - actionList
      not:
        required: [ dnsQueryMdtList, dnsRspMdtList ]

    DnsQueryMdt:
      description: DNS Query message detection template 
      type: object
      properties:
        sourceIpv4Addr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv4Addr'
        sourceipv6Addr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv6Addr'
        fqdnList:
          type: array
          items:
            type: string
          minItems: 1

    DnsRspMdt:
      description: DNS Response message detection template 
      type: object
      properties:
        fqdnList:
          type: array
          items:
            type: string
          minItems: 1
        easIpv4AddrRanges:
          type: array
          items:
            $ref: '#/components/schemas/Ipv4AddressRange'
          minItems: 1
        easIpv6PrefixRanges:
          type: array
          items:
            $ref: '#/components/schemas/Ipv6PrefixRange'
          minItems: 1

    Ipv4AddressRange:
      description: Range of IPv4 addresses
      type: object
      properties:
        start:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv4Addr'
        end:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv4Addr'
      required:
        - start
        - end

    Ipv6PrefixRange:
      description: Range of IPv6 prefixes
      type: object
      properties:
        start:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv6Prefix'
        end:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv6Prefix'
      required:
        - start
        - end

    Action:
      description: Action to apply to DNS messages matching a message detection template 
      type: object
      properties:
        applyAction:
          $ref: '#/components/schemas/ApplyAction'
        fwdParas:
          $ref: '#/components/schemas/ForwardingParameters'
        reportingOnceInd:
          type: boolean
          default: false
        resetReportingOnceInd:
          type: boolean
          default: false
      required:
        - applyAction

    DnsContextNotification:
      description: Data within DNS Context Notify 
      type: object
      properties:
        eventReportList:
          type: array
          items:           
            $ref: '#/components/schemas/DnsContextEventReport'
          minItems: 1

    ForwardingParameters:
      description: Forwarding instructions
      type: object
      properties:
        ecsOption:
          $ref: '#/components/schemas/EcsOption'
        dnsServerAddress:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/IpAddr'
        usePreconfiguredDnsServer:
          type: boolean

    EcsOption:
      description: ECS Option Information 
      type: object
      properties:
        sourcePrefixLength:
          type: integer
          minimum: 0
          maximum: 128
        scopePrefixLength:
          type: integer
          minimum: 0
          maximum: 128
        ipAddr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/IpAddr'
      required:
        - sourcePrefixLength
        - ipAddr

    DnsContextEventReport:
      description: DNS context event report 
      type: object
      properties:
        dnsRuleId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uint32'
        dnsQueryReport:
          $ref: '#/components/schemas/DnsQueryReport'
        dnsRspReport:
          $ref: '#/components/schemas/DnsRspReport'


    DnsQueryReport:
      description: DNS Query Event Report
      type: object
      properties:
        fqdn:
          type: string

    DnsRspReport:
      description: DNS Response Event Report
      type: object
      properties:
        fqdn:
          type: string
        easIpv4Addresses:
          type: array
          items: 
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv4Addr'
          minItems: 1
        easIpv6Addresses:
          type: array
          items: 
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv6Addr'
          minItems: 1
        ecsOption:
          $ref: '#/components/schemas/EcsOption'

#
# SIMPLE DATA TYPES
#



#
# ENUMERATIONS
#

    ApplyAction:
      anyOf:
      - type: string
        enum:
          - BUFFER
          - REPORT
          - FORWARD
          - DISCARD
      - 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: >
        Action to apply to the DNS packet 
