openapi: 3.0.0

info:
  version: '1.0.0.alpha-2'
  title: 'Nhss_imsUECM'
  description: |
    Nhss UE Context Management Service for IMS.
    © 2020, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.

externalDocs:
  description: 3GPP TS 29.562 Unified Data Management Services, version 16.0.0
  url: 'http://www.3gpp.org/ftp/Specs/archive/29_series/29.562/'

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

security:
  - oAuth2ClientCredentials:
    - nhss-ims-uecm
  - {}

paths:

  /{impu}/authorize:
    post:
      summary: Authorize IMS Identities to register in the network or establish multimedia sessions and return CSCF location if it is stored 
      operationId: Authorize
      tags:
        - Authorize Ims identities
      parameters:
        - name: impu
          in: path
          description: Public identity of the user. 
          required: true
          schema:
              $ref: '#/components/schemas/Impu'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
        required: true
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error
      callbacks:
        deregistrationeNotification:
          '{request.body#/deregCallbackUri}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/DeregistrationData'
              responses:
                '204':
                  description: Successful Notification response
                '400':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/400'
                '404':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/404'
                '500':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/500'
                '503':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/503'
                default:
                  description: Unexpected error

  /{imsUeId}/scscf-registration:
    put:
      summary: SCSCF registration information
      operationId: SCSCF registration
      tags:
        - SCSCF registration and deregistration
      parameters:
        - name: imsUeId
          in: path
          description: IMS Identity
          required: true
          schema:
            $ref: '#/components/schemas/ImsUeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScscfRegistration'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScscfRegistration'
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScscfRegistration'
        '204':
          description: No content
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ExtendedProblemDetails'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error

  /{impu}/scscf-registration/scscf-restoration-info:
      put:
        summary: Update the S-CSCF restoration information of the UE
        operationId: UpdateScscfRestorationInfo
        tags:
          - Update the S-CSCF restoration information of the UE
        parameters:
          - name: impu
            in: path
            description: Public identity of the user.
            required: true
            schema:
              $ref: '#/components/schemas/Impu'
        requestBody:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScscfRestorationInfoRequest'
          required: true
        responses:
          '201':
            description: Created
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ScscfRestorationInfoResponse'
            headers:
              Location:
                description: 'Contains the URI of the newly created resource, according to the structure: {apiRoot}/nhss_imsUECM/v1/{impu}/scscf-registration/scscf-restoration-info'
                required: true
                schema:
                  type: string
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ScscfRestorationInfoResponse'
          '204':
            description: No content
          '403':
            $ref: 'TS29571_CommonData.yaml#/components/responses/403'
          
      get:
        summary: Retrieve the S-CSCF restoration
        operationId: GetScscfRestorationInfo
        tags:
         - S-CSCF Restoration Info Retrieval
        parameters:
          - name: impu
            in: path
            description: Public identity of the user.
            required: true
            schema:
              $ref: '#/components/schemas/Impu'
        responses:
          '200':
            description: Expected response to a valid request
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ScscfRestorationInfoResponse'
          '404':
            $ref: 'TS29571_CommonData.yaml#/components/responses/404'
          
      delete:
        summary: Delete the S-CSCF restoration
        operationId: DeleteScscfRestorationInfo
        tags:
         - S-CSCF Restoration Info Delete
        parameters:
          - name: impu
            in: path
            description: Public identity of the user.
            required: true
            schema:
              $ref: '#/components/schemas/Impu'
        responses:
          '204':
            description: No content
          '403':
            $ref: 'TS29571_CommonData.yaml#/components/responses/403'
          '404':
            $ref: 'TS29571_CommonData.yaml#/components/responses/404'

components:

  schemas:

# COMPLEX TYPES:

    AuthorizationRequest:
      description: Ims authorization request data
      type: object
      required:
        - authorizationType
      properties:
        impi:
          $ref: '#/components/schemas/Impi'
        authorizationType:
          description: authorization type
          $ref: '#/components/schemas/AuthorizationType'
        visitedNetworkIdentifier:
          type: string
        emergencyIndicator:
          type: boolean
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

    AuthorizationResponse:
      description: Ims Registration authorization information result
      type: object
      properties:
        authorizationResult:
          $ref: '#/components/schemas/AuthorizationResult'
        cscfServerName:
          type: string
        
    ScscfRegistration:
      description: Scscf Registration
      type: object
      required:
        - imsRegistrationType
        - cscfServerName
      properties:
        impi:
          $ref: '#/components/schemas/Impi'
        imsRegistrationType:
          description: Ims registration type
          $ref: '#/components/schemas/ImsRegistrationType'
        cscfServerName:
          type: string
        scscfInstanceId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/NfInstanceId'
        deregCallbackUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        associatedImpis:
          type: array
          items:
            $ref: '#/components/schemas/Impi'
        irsImpus:
          type: array
          items:
            $ref: '#/components/schemas/Impu'
          minItems: 1
          uniqueItems: true
        wildcardedPui:
          $ref: '#/components/schemas/Impu'
        looseRouteIndicator:
          $ref: '#/components/schemas/LooseRouteIndication'
        wildcardedPsi:
          $ref: '#/components/schemas/Impu'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

    ExtendedProblemDetails:
      allOf:
      - $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
      - $ref: '#/components/schemas/AdditionalInfo'

    AdditionalInfo:
      type: object
      properties:
        scscfServerName:
          type: string

    ScscfRestorationInfo:
      description: S-CSCF restoration information
      type: object
      properties:
        userName:
          $ref: '#/components/schemas/Impi'
        restorationInfo:
          type: array
          items:
            $ref: '#/components/schemas/RestorationInfo'
        registrationTimeOut:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        sipAuthenticationScheme:
            $ref: '#/components/schemas/SipAuthenticationScheme'
          
    ScscfRestorationInfoRequest:
      description: S-CSCF restoration information request
      type: object
      properties:
        scscfRestorationInfoRequest:
          $ref: '#/components/schemas/ScscfRestorationInfo'
          
    ScscfRestorationInfoResponse:
      description: S-CSCF restoration information response
      type: object
      properties:
        scscfRestorationInfoResponse:
          type: array
          items:
            $ref: '#/components/schemas/ScscfRestorationInfo'

    RestorationInfo:
      description: The information relevant to a specific registration required for an S-CSCF to handle the requests for a user
      type: object
      required:
        - path
        - contact
      properties:
        path:
          type: string
        contact:
          type: string
        initialCSeqSequenceNumber:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uint32'
        callIdSipHeader:
          type: string
        uesubscriptionInfo:
          $ref: '#/components/schemas/UeSubscriptionInfo'
        pcscfSubscriptionInfo:
          $ref: '#/components/schemas/PcscfSubscriptionInfo'

    UeSubscriptionInfo:
      type: object
      required:
        - callIdSipHeader
        - fromSipHeader
        - toSipHeader
        - recordRoute           
        - contact             
      properties:
        callIdSipHeader:
          type: string
        fromSipHeader:
          type: string
        toSipHeader:
          type: string
        recordRoute:
          type: string
        contact:
          type: string 

    PcscfSubscriptionInfo:
      type: object
      required:
        - callIdSipHeader
        - fromSipHeader
        - toSipHeader
        - contact             
      properties:
        callIdSipHeader:
          type: string
        fromSipHeader:
          type: string
        toSipHeader:
          type: string
        contact:
          type: string  

    DeregistrationData:
      type: object
      required:
        - deregReason
        - impi
      properties:
        deregReason:
          $ref: '#/components/schemas/DeregistrationReason'
        impi:
          $ref: '#/components/schemas/Impi'
        associatedImpis:
          type: array
          items:
            $ref: '#/components/schemas/Impi'
        emergencyRegisteredIdentities:
          type: array
          items:
            $ref: '#/components/schemas/EmergencyRegisteredIdentity'
          minItems: 1

    EmergencyRegisteredIdentity:
      type: object
      required:
        - impi
        - impu
      properties:
        impi:
          $ref: '#/components/schemas/Impi'
        impu:
          $ref: '#/components/schemas/Impu'

    DeregistrationReason:
      type: object
      required:
        - reasonCode
        - reasonText
      properties:
        reasonCode:
          $ref: '#/components/schemas/DeregistrationReasonCode'
        reasonText:
          type: string

# SIMPLE TYPES

    ImsUeId:
      type: string
      pattern: '^(impu-sip\:([a-zA-Z0-9_\-.!~*()&=+$,;?\/]+)\@([A-Za-z0-9]+([-A-Za-z0-9]+)\.)+[a-z]{2,}|impu-tel\:\+[0-9]{5,15}|impi-.+|.+)$'

    Impu:
      type: string
    Impi:
      type: string

# ENUMS:

    AuthorizationType:
      anyOf:
        - type: string
          enum:
          - REGISTRATION
          - DEREGISTRATION
        - type: string

    AuthorizationResult:
      anyOf:
        - type: string
          enum:
          - FIRST_REGISTRATION
          - SUBSEQUENT_REGISTRATION
        - type: string

    SipAuthenticationScheme:
      anyOf:
        - type: string
          enum:
          - DIGEST-AKAV1-MD5
          - DIGEST-HTTP
          - NBA
          - GIBA
          - UNKNOWN
        - type: string

    ImsRegistrationType:
      anyOf:
        - type: string
          enum:
          - INITIAL_REGISTRATION
          - RE_REGISTRATION
          - TIMEOUT_DEREGISTRATION
          - USER_DEREGISTRATION
          - ADMINISTRATIVE_DEREGISTRATION
          - AUTHENTICATION_FAILURE
          - AUTHENTICATION_TIMEOUT
        - type: string

    LooseRouteIndication:
      anyOf:
        - type: string
          enum:
          - LOOSE_ROUTE_NOT_REQUIRED
          - LOOSE_ROUTE_REQUIRED
        - type: string

    DeregistrationReasonCode:
      anyOf:
        - type: string
          enum:
          - PERMANENT_TERMINATION
          - NEW_SERVER_ASSIGNED
          - REMOVE_S-CSCF
          - SERVER_CHANGE
        - type: string