api/ric-dms-api.yaml

# ==================================================================================
#   Copyright (c) 2021 Samsung.
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#          http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.
#
#   This source code is part of the near-RT RIC (RAN Intelligent Controller)
#   platform project (RICP).
# ==================================================================================

openapi: 3.0.1
info:
  title: RIC DMS API
  description: APIs for RIC-DMS
  version: "1.0"
servers:
- url: /api/v1
tags:
- name: onboard
  description: onboard xApps
- name: health
  description: health check
- name: charts
  description: Managing helm charts
- name: deploy
  description: Managing deployment
paths:
  /charts:
    get:
      tags:
      - charts
      summary: Returns the list of xApp helm charts that have been onboarded
      operationId: get_charts_list
      responses:
        200:
          description: Get helm chart list
          content:
            application/json:
              schema:
                type: object
        500:
          description: Get helm chart list failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'

  /charts/xApp/{xApp_name}:
    get:
      tags:
      - charts
      summary: Returns the helm chart for the specified xApp
      operationId: get_chart
      parameters:
      - name: xApp_name
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: Get helm chart
          content:
            application/json:
              schema:
                type: object
        500:
          description: Get helm chart failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'

  /charts/xApp/{xApp_name}/ver/{version}:
    get:
      tags:
      - charts
      summary: get the helm chart for the specified xApp and version
      operationId: get_charts_fetcher
      parameters:
      - name: xApp_name
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: Get helm chart package OK
          content:
            application/json:
              schema:
                type: object
        500:
          description: Get helm chart package failed
          content:
            application/gzip:
              schema:
                $ref: '#/components/schemas/error_message'
    delete:
      tags:
      - charts
      summary: Delete helm chart for the specified xApp and version
      operationId: delete_chart
      parameters:
      - name: xApp_name
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: Deleted specified helm chart
          content:
            application/json:
              schema:
                type: object
        500:
          description: Delete helm chart failed
          content:
            application/gzip:
              schema:
                $ref: '#/components/schemas/error_message'

  /charts/xApp/download/{xApp_name}/ver/{version}:
    get:
      tags:
      - charts
      summary: Download helm chart
      description: Download helm chart.
      operationId: download_helm_chart
      parameters:
      - name: xApp_name
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: Download helm chart OK
          content:
            application/zip:
              schema:
                type: string
                format: binary
        500:
          description: Get helm chart values.yaml failed
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/error_message'

  /charts/xApp/{xApp_name}/ver/{version}/values.yaml:
    get:
      tags:
      - charts
      summary: Returns the helm values
      description: yaml file of the specified xApp and version.
      operationId: get_values_yaml_fetcher
      parameters:
      - name: xApp_name
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: Get helm chart values.yaml OK
          content:
            application/json:
              schema:
                type: object
        500:
          description: Get helm chart values.yaml failed
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/error_message'

  /health:
    get:
      tags:
      - health
      summary: Returns the health condition of ric dms
      operationId: get_health_check
      responses:
        200:
          description: Health check OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
        500:
          description: ric-dms is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'

  /healthcheck/xApp/{xApp_name}/namespace/{namespace}:
    get:
      tags:
      - health
      summary: Return status of xApp deployment
      parameters:
        - name: xApp_name
          in: path
          required: true
          schema:
            type: string
        - name: namespace
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Health check OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
        500:
          description: xApp onboarder is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'

  /onboarder:
    post:
      tags:
      - onboard
      summary: Onboard xApp using the xApp descriptor and schema or URL of descriptor and schema.
      operationId: post_onboardx_apps
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/descriptor'
        required: true
      responses:
        201:
          description: xApp onboard successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
        400:
          description: xApp descriptor format error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        500:
          description: xApp onboarder is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      x-codegen-request-body-name: payload
    delete:
      tags:
      - onboard
      summary: offload xApp using the xApp name and version
      operationId: delete_onboardx_apps
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - appname
              properties:
                appname:
                  type: string
                version:
                  type: string
      responses:
        201:
          description: xApp onboard successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
        400:
          description: xApp descriptor format error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        500:
          description: xApp onboarder is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      x-codegen-request-body-name: payload

  /deploy:
    post:
      tags:
      - deploy
      summary: deploy xApp
      requestBody:
        description: Input for the xApp deployment
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deploymentDesc'
      responses:
        201:
          description: successful deployment of xApp
          content:
            application/json:
              schema:
                type: object
        501:
          description: deployment failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'

    put:
      tags:
      - deploy
      summary: update xApp
      requestBody:
        description: Input for the xApp deploy
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateDeploymentDesc'

      responses:
        201:
          description: successful updated xApp
          content:
            application/json:
              schema:
                type: object
        501:
          description: un-deployment failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    delete:
      tags:
      - deploy
      summary: Undeploy xApp
      requestBody:
        description: Input for the xApp deploy
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deleteDeploymentDesc'
      responses:
        201:
          description: successful un-deploy xApp
          content:
            application/json:
              schema:
                type: object
        501:
          description: un-deployment failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'



components:
  schemas:
    name:
      type: object
      properties:
        property:
          type: integer
    descriptor:
      type: object
      properties:
        config:
          type: string
          description: represents content of config file for xApp onboarding.
        schema:
          type: string
          description: represents conent of schema file for xApp onboarding.
        config-file_url:
          type: string
          description: specify url of config-file.
        schema-file_url:
          type: string
          description: specify url of schema-file.

    deploymentDesc:
      required:
      - namespace
      type: object
      properties:
        xAppname:
          type: string
        version:
           type: string
        namespace:
          type: string
          description: namespace to deploy xApp
        overridefile:
          type: string
          description: override file

    updateDeploymentDesc:
      required:
      - namespace
      type: object
      properties:
        xAppname:
          type: string
        oldVersion:
          type: string
        newVersion:
          type: string
        namespace:
          type: string
          description: namespace to deploy xApp
        operation:
          type: string
          enum:
          - rollback
          - upgrade

    deleteDeploymentDesc:
      required:
      - xAppname
      - version
      type: object
      properties:
        xAppname:
          type: string
        version:
          type: string
        namespace:
          type: string
          description: namespace to deploy xApp

    error_message:
      required:
      - error_message
      - error_source
      - status
      type: object
      properties:
        error_source:
          type: string
          description: source of the error
        error_message:
          type: string
          description: source of the error
        status:
          type: string
          description: http response message
    status:
      required:
      - status
      type: object
      properties:
        status:
          type: string
          description: status of the service