openapi.yaml

# This is an **example** API to demonstrate features of PredictaaS API using an OpenAPI specification

openapi: 3.0.2
info:
  version: '1.0.0' # Your API version
  # It can be any string but it is better to use semantic versioning: http://semver.org/
  # Warning: OpenAPI requires the version to be a string, but without quotation marks YAML can recognize it as a number.

  title: PredictaaS # Replace with your API title
  # Keep it simple. Don't add "API" or version at the end of the string.

  termsOfService: 'https://example.com/terms/' # [Optional] Replace with an URL to your ToS
  contact:
    email: contact@example.com # [Optional] Replace with your contact email
    url: 'http://example.com/contact' # [Optional] Replace with link to your contact form
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  x-logo:
    url: 'https://redocly.github.io/openapi-template/logo.png'

  # Describe your API here, you can use GFM (https://guides.github.com/features/mastering-markdown) here
  description: |
    This is a **sample** API for the PredictaaS web service.
    # Introduction
    This API specification is intended to provide a skeleton for the required API paths expected for the
    PredictaaS ML web service. It is OpenAPI v3 compliant, check out
    [OpenAPI format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) for additional
    features.

# A list of tags used by the definition with additional metadata.
# The order of the tags can be used to reflect on their order by the parsing tools.
tags:
  - name: Echo
    description: Example echo operations
  - name: App
    description: Operations about app
servers:
  - url: 'http://example.com/api/v1'
  - url: 'https://example.com/api/v1'

# Holds the relative paths to the individual endpoints. The path is appended to the
# basePath in order to construct the full URL.
paths:
  '/mlapp':
    get: # documentation for GET operation for this path
      tags:
        - App

      # summary is up to 120 symbold but we recommend to be shortest as possible
      summary: Get ML applications

      # you can use GFM in operation description too: https://guides.github.com/features/mastering-markdown
      description: |
        Some description of the operation.
        You can use `markdown` here.

      # operationId should be unique across the whole specification
      operationId: getMLApps

      responses: # list of responses
        '200':
          description: Success
          content:
            application/json: # operation response mime type
              schema: # response schema can be specified for each response
                $ref: '#/components/schemas/MLApp'
              example: # response example
                appname: fooapp
        '403':
          description: Forbidden
        '404':
          description: Application not found
  '/mlapp/{appname}':
    get: # documentation for GET operation for this path
      tags:
        - App

      # summary is up to 120 symbold but we recommend to be shortest as possible
      summary: Get ML application by name

      # you can use GFM in operation description too: https://guides.github.com/features/mastering-markdown
      description: |
        Some description of the operation.
        You can use `markdown` here.

      # operationId should be unique across the whole specification
      operationId: getMLAppByName

      # list of parameters for the operation
      parameters:
        - name: appname
          in: path
          description: The name that needs to be fetched
          required: true
          schema:
            type: string

      responses: # list of responses
        '200':
          description: Success
          content:
            application/json: # operation response mime type
              schema: # response schema can be specified for each response
                $ref: '#/components/schemas/MLApp'
              example: # response example
                appname: fooapp
        '403':
          description: Forbidden
        '404':
          description: Application not found
    # documentation for PUT operation for this path
    put:
      tags:
        - App
      summary: Updated app
      description: Update ML application by name.
      operationId: updateMLApp
      parameters:
        - name: appname
          in: path
          description: The name that needs to be updated
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Invalid application name supplied
        '404':
          description: App not found
      # request body documentation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MLApp'
          application/xml:
            schema:
              $ref: '#/components/schemas/MLApp'
        description: Updated user object
        required: true

# An object to hold reusable parts that can be used across the definition
components:
  schemas:
    Email:
      description: Main contact email address
      type: string
      format: test
      example: jane.doe@example.com
    MLApp:
      type: object
      properties:
        appname:
          description: ML app supplied username
          type: string
          minLength: 4
          example: PlantClassificator
        entrypoint:
          description: Python's app entrypoint name
          type: string
          minLength: 1
          example: plant_classificator
        methods:
          description: Methods implemented by the ML app
          type: string
          enum: [predict, train]
          minLength: 1
          example:
            - predict
            - train
        contact:
          $ref: '#/components/schemas/Email'