openapi: 3.0.0
info:
  version: '0.1.0'
  title: 'OsmoS1GW REST interface'

paths:
  /metrics-list:
    get:
      summary: Get a list of metrics
      operationId: MetricsList
      parameters:
        - name: type
          in: query
          description: Metric type
          required: false
          schema:
            type: string
            enum: [all, counter, gauge]
            default: all
        - name: path
          in: query
          description: Metrics path
          required: false
          schema:
            type: string
            example: s1ap.proxy
      responses:
        '200':
          description: A list of metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsList'

  /pfcp/assoc:
    get:
      summary: Get the PFCP association state
      operationId: PfcpAssocState
      responses:
        '200':
          description: PFCP association state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PfcpAssocState'
    post:
      summary: Initiate the PFCP Association Setup procedure
      operationId: PfcpAssocSetup
      responses:
        '200':
          $ref: '#/components/responses/OperationResult'
    delete:
      summary: Initiate the PFCP Association Release procedure
      operationId: PfcpAssocRelease
      responses:
        '200':
          $ref: '#/components/responses/OperationResult'

  /pfcp/heartbeat:
    post:
      summary: Send a PFCP Heartbeat Request to the peer
      operationId: PfcpHeartbeat
      responses:
        '200':
          $ref: '#/components/responses/OperationResult'

  /enb-list:
    get:
      summary: Get a list of eNB connections
      operationId: EnbList
      responses:
        '200':
          description: A list of eNB connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnbList'

  /enb/{EnbId}:
    get:
      summary: Get information about a specific eNB
      operationId: EnbInfo
      parameters:
        - $ref: '#/components/parameters/EnbId'
      responses:
        '200':
          description: Successful outcome (eNB info)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnbItem'
        '404':
          description: Unsuccessful outcome (eNB not found)

  /enb/{EnbId}/erab-list:
    get:
      summary: Get E-RAB list for a specific eNB
      operationId: EnbErabList
      parameters:
        - $ref: '#/components/parameters/EnbId'
      responses:
        '200':
          description: Successful outcome (E-RAB list)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErabList'
        '404':
          description: Unsuccessful outcome (eNB not found)

  /erab-list:
    get:
      summary: Get E-RAB list for all eNBs
      operationId: ErabList
      responses:
        '200':
          description: A list of E-RABs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErabList'

  /erab/{ErabId}:
    get:
      summary: Get information about a specific E-RAB
      operationId: ErabInfo
      parameters:
        - $ref: '#/components/parameters/ErabId'
      responses:
        '200':
          description: Successful outcome (E-RAB info)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErabItem'
        '404':
          description: Unsuccessful outcome (E-RAB not found)

components:
  responses:
    OperationResult:
      description: Generic operation result response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationResult'

  parameters:
    EnbId:
      name: EnbId
      in: path
      description: eNB identifier (selector)
      required: true
      schema:
        oneOf:
          - type: string
            pattern: '^handle:[0-9]+$'
            description: Unique identifier in the eNB registry
            example: handle:42
          - type: string
            pattern: '^pid:[0-9]+\.[0-9]+\.[0-9]+$'
            description: Process ID
            example: pid:0.33.1
          - type: string
            pattern: '^genbid:[0-9]{3}-[0-9]{2,3}-[0-9]+$'
            description: Global-eNB-ID (MCC-MNC-eNBId)
            example: genbid:999-70-1337
          - type: string
            pattern: '^(enb|mme)-sctp-aid:[0-9]+$'
            description: eNB/MME SCTP association identifier
            example: enb-aid:42
          - type: string
            pattern: '^enb-conn:[0-9:.]+-[0-9]+$'
            description: eNB connection address/port
            example: enb-conn:192.168.1.1-34650

    ErabId:
      name: ErabId
      in: path
      description: E-RAB identifier (selector)
      required: true
      schema:
        oneOf:
          - type: string
            pattern: '^pid:[0-9]+\.[0-9]+\.[0-9]+$'
            description: Process ID
            example: pid:0.33.1

  schemas:
    OperationResult:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: Indicates whether the operation was successful
        message:
          type: string
          nullable: true
          description: Human-readable explanation of the result

    Pid:
      type: string
      pattern: '^<[0-9]+\.[0-9]+\.[0-9]+>$'
      description: Process ID

    MetricsList:
      type: array
      items:
        $ref: '#/components/schemas/MetricsItem'

    MetricsItem:
      type: object
      required:
        - type
        - name
        - value
      properties:
        type:
          type: string
          enum: [counter, gauge]
        name:
          type: string
        value:
          type: integer

    PfcpAssocState:
      type: object
      required:
        - state
        - laddr
        - raddr
      properties:
        state:
          type: string
          enum: [connecting, connected]
          description: Current association state
        laddr:
          type: string
          description: Local (bind) IP address
        raddr:
          type: string
          description: Remote (connect) IP address
        lrts:
          type: integer
          description: Local Recovery TimeStamp
        rrts:
          type: integer
          description: Remote Recovery TimeStamp

    EnbList:
      type: array
      items:
        $ref: '#/components/schemas/EnbItem'

    EnbItem:
      type: object
      required:
        - handle
        - pid
        - state
        - uptime
        - erab_count
      properties:
        handle:
          type: integer
          description: Unique number in the eNB registry
        pid:
          $ref: '#/components/schemas/Pid'
        state:
          type: string
          enum: [connecting, connected, s1setup]
          description: Connection state
        uptime:
          type: integer
          description: Uptime (in seconds)
        erab_count:
          type: integer
          description: Total number of E-RABs
        genb_id:
          type: string
          pattern: '^[0-9]{3}-[0-9]{2,3}-[0-9]+$'
          example: 001-01-1337
          description: Global-eNB-ID
        enb_saddr:
          type: string
          description: Source (remote) address of the eNB
        mme_daddr:
          type: string
          description: Destination (remote) address of the MME
        enb_sport:
          type: integer
          description: Source (remote) port of the eNB-S1GW connection
        mme_sport:
          type: integer
          description: Source (local) port of the S1GW-MME connection
        mme_dport:
          type: integer
          description: Destination (remote) port of the S1GW-MME connection
        enb_sctp_aid:
          type: integer
          description: SCTP association identifier of the eNB-S1GW connection
        mme_sctp_aid:
          type: integer
          description: SCTP association identifier of the S1GW-MME connection

    ErabList:
      type: array
      items:
        $ref: '#/components/schemas/ErabItem'

    FTEID:
      type: object
      required:
        - teid
        - tla
      properties:
        teid:
          type: integer
          description: GTP-U TEID
        tla:
          type: string
          description: GTP-U TLA (Transport Layer Address)

    ErabItem:
      type: object
      required:
        - mme_ue_id
        - erab_id
        - state
        - pid
      properties:
        mme_ue_id:
          type: integer
          description: MME-UE-S1AP-ID
        erab_id:
          type: integer
          description: E-RAB-ID
        state:
          type: string
          description: E-RAB FSM state
          example: erab_wait_release_rsp
        pid:
          type: string
          pattern: '^<[0-9]+\.[0-9]+\.[0-9]+>$'
          description: E-RAB FSM process ID
        pfcp_lseid:
          type: integer
          description: PFCP SEID (local)
        pfcp_rseid:
          type: integer
          description: PFCP SEID (remote)
        f_teid_u2c:
          $ref: '#/components/schemas/FTEID'
          description: GTP-U F-TEID for UPF -> Core
        f_teid_c2u:
          $ref: '#/components/schemas/FTEID'
          description: GTP-U F-TEID for UPF <- Core
        f_teid_a2u:
          $ref: '#/components/schemas/FTEID'
          description: GTP-U F-TEID for UPF <- Access
        f_teid_u2a:
          $ref: '#/components/schemas/FTEID'
          description: GTP-U F-TEID for UPF -> Access