openapi: 3.0.3

info:
  title: Reverse Proxy as a Service
  description: |
    The presented API definition (formally called as RPaaS v2 API) is a superset of [Tsuru Service API] and the [legacy RPaaS][RPaaS v1 API] (aka RPaaS v1).

    Source code: [github.com/tsuru/rpaas-operator](https://github.com/tsuru/rpaas-operator.git)

    [Tsuru Service API]: https://app.swaggerhub.com/apis/tsuru/tsuru-service_api
    [RPaaS v1 API]: https://raw.githubusercontent.com/tsuru/rpaas/master/rpaas/api.py
  contact:
    name: Tsuru
    email: tsuru@g.globo
  version: v2
  license:
    name: BSD-3-Clause License
    url: https://raw.githubusercontent.com/tsuru/rpaas-operator/master/LICENSE

security:
- basicAuth: []

tags:
- name: rpaas
  description: RPaaS v2's web API specification.
- name: rpaas-purger
  description: RPaaS v2 Purger's web API specification.

paths:
  /healthcheck:
    get:
      summary: Check the API healthiness
      operationId: Healthcheck
      security: []
      tags:
      - rpaas
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: WORKING
        default:
          description: Not OK

  /resources:
    post:
      summary: Create an instance
      description: This endpoint is part of Tsuru Service API.
      operationId: CreateInstance
      tags:
      - rpaas
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstance'
      responses:
        '201':
          description: Created
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Instance already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unknown error
          content:
            text/plain:
              example: failed to create instance on storage

  /resources/{instance}:
    parameters:
    - in: path
      name: instance
      schema:
        type: string
      required: true
      description: Instance name
    delete:
      summary: Delete an instance
      description: This endpoint is part of Tsuru Service API.
      operationId: DeleteInstance
      tags:
      - rpaas
      responses:
        '200':
          description: Deleted
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unknown error
          content:
            text/plain:
              example: failed to create instance on storage
    get:
      summary: Get additional information about an instance
      description: This endpoint is part of Tsuru Service API.
      operationId: GetInstance
      tags:
      - rpaas
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AdditionalInstanceInfo'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unknonw error
          content:
            text/plain:
              schema:
                type: string
              example: an unknown error
    put:
      summary: Update an instance
      description: This endpoint is part of Tsuru Service API.
      operationId: UpdateInstance
      tags:
      - rpaas
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateInstance'
      responses:
        '200':
          description: Updated
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unknown error
          content:
            text/plain:
              example: failed to create instance on storage

  /resources/{instance}/status:
    get:
      summary: Whether instance is running or not
      description: This endpoint is part of Tsuru Service API.
      tags:
      - rpaas
      parameters:
      - in: path
        name: instance
        schema:
          type: string
        required: true
        description: Instance name
      responses:
        '202':
          description: Instance is pending (partially provisioned)
        '204':
          description: Instance is up and running

  /resources/{instance}/bind-app:
    parameters:
      - name: instance
        in: path
        description: Instance name
        required: true
        schema:
          type: string

    post:
      summary: Binds the app to the rpaas instance
      description: This endpoint is part of Tsuru Service API.
      operationId: BindApp
      tags:
      - rpaas
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BindApp'
      responses:
        '201':
          description: App successfully bound to the rpaas instance
        '404':
          description: rpaas instance does not exist
        '412':
          description: rpaas instance not ready

  /resources/{instance}/bind:
    parameters:
      - name: instance
        in: path
        description: Instance name
        required: true
        schema:
          type: string

    post:
      operationId: BindInstance
      deprecated: true
      summary: Bind Unit
      description: Not used, just to follow Tsuru Service API spec
      tags:
      - rpaas
      responses:
        '200':
          description: Nothing happens

    delete:
      operationId: UnbindInstance
      deprecated: true
      summary: Unbind Unit
      description: Not used, just to follow Tsuru Service API spec
      tags:
      - rpaas
      responses:
        '200':
          description: Nothing happens

  /resources/plans:
    get:
      summary: List supported plans
      description: This endpoint is part of Tsuru Service API.
      operationId: ListPlans
      tags:
      - rpaas
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plan'
        default:
          description: An unknown error
          content:
            text/plain:
              example: failed to get plans from storage

  /resources/flavors:
    get:
      summary: List supported flavors
      description: |-
        This endpoint is part of legacy RPaaS API.

        Deprecated in favor of `GET /resources/plans` (see the supported flavors within `schemas` field of `Plan` object).
      operationId: ListFlavors
      deprecated: true
      tags:
      - rpaas
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flavor'
        default:
          description: An unknown error
          content:
            text/plain:
              example: failed to get flavors from storage

  /resources/{instance}/flavors:
    get:
      summary: List flavors by instance
      description: |-
        This endpoint is part of legacy RPaaS API.

        Deprecated in favor of `GET /resources/plans` (see the supported flavors within `schemas` field of `Plan` object).
      operationId: ListFlavorsByInstance
      deprecated: true
      tags:
      - rpaas
      parameters:
      - in: path
        name: instance
        schema:
          type: string
        required: true
        description: Instance name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flavor'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An unknown error
          content:
            text/plain:
              example: failed to get flavors from storage

  /resources/{instance}/plans:
    get:
      summary: List supported plans by instance
      description: This endpoint is part of legacy RPaaS API.
      operationId: ListPlansByInstance
      deprecated: true
      tags:
      - rpaas
      parameters:
      - in: path
        name: instance
        schema:
          type: string
        required: true
        description: Instance name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plan'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
        default:
          description: An unknown error
          content:
            text/plain:
              example: failed to get plans from storage

  /resources/{instance}/info:
    get:
      summary: Get a summary info about an instance
      operationId: GetInstanceInfo
      tags:
      - rpaas
      parameters:
      - in: path
        name: instance
        schema:
          type: string
        required: true
        description: Instance name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceInfo'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unknonw error
          content:
            text/plain:
              schema:
                type: string
              example: an unknown error

  /resources/{instance}/purge:
    parameters:
      - name: instance
        in: path
        description: Instance name
        required: true
        schema:
          type: string
    post:
      summary: Purge cache key of rpaasv2.
      description: |-
        This endpoint is exclusive for RPaaS v2 API.
      operationId: PurgeCache
      tags:
      - rpaas
      parameters:
      - in: path
        name: instance
        schema:
          type: string
        required: true
        description: Instance name
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Purge'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                example: "Object purged on 2 servers"
        '400':
          description: Body or instance name empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /resources/{instance}/autoscale:
    parameters:
    - name: instance
      in: path
      description: Instance name
      required: true
      schema:
        type: string

    get:
      summary: Get reverse proxy instance autoscaling parameters
      operationId: GetAutoscale
      tags:
      - rpaas
      security:
      - basicAuth: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Autoscale"
        default:
          description: Something wrong happened
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: Set reverse proxy the autoscaling parameters
      operationId: CreateAutoscale
      tags:
      - rpaas
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          "application/json":
            example:
              minReplicas: 3
              maxReplicas: 100
              cpu: 75
            schema:
              $ref: "#/components/schemas/Autoscale"
      responses:
        "201":
          description: Succesfully created
        default:
          description: Something wrong happened
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: Update the reverse proxy instance autoscaling parameters
      operationId: UpdateAutoscale
      tags:
      - rpaas
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          "application/json":
            example:
              minReplicas: 1
              maxReplicas: 50
              rps: 50
            schema:
              $ref: "#/components/schemas/Autoscale"
      responses:
        "204":
          description: Succesfully updated
        default:
          description: Something wrong happened
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: Remove the reverse proxy instance autoscaling capability
      operationId: RemoveAutoscale
      tags:
      - rpaas
      security:
      - basicAuth: []
      responses:
        "204":
          description: Succesfully removed
        default:
          description: Something wrong happened
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /resources/{instance}/purge/bulk:
    parameters:
      - name: instance
        in: path
        description: Instance name
        required: true
        schema:
          type: string
    post:
      summary: Purge objects from rpaasv2.
      description: |-
        This endpoint is exclusive for RPaaS v2 API.
      operationId: PurgeBulkCache
      tags:
      - rpaas-purger
      parameters:
      - in: path
        name: instance
        schema:
          type: string
        required: true
        description: Instance name
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Purge'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurgeBulkResponse'
        '400':
          description: Body or instance name empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

  schemas:
    AdditionalInstanceInfo:
      type: object
      properties:
        label:
          type: string
          example: Address
        value:
          type: string
          example: 169.254.254.100

    Autoscale:
      type: object
      properties:
        minReplicas:
          description: |
            The lower limit for the number of replicas to which the autoscaler can scale down.
            It cannot be greater than `maxReplicas`.
            It can be zero when set along with `rps` and/or `schedules` targets.
          type: integer
          example: 3
          minimum: 1
        maxReplicas:
          description: |
            The upper limit for the number of replicas to which the autoscaler can scale up.
            It cannot be less that `minReplicas`.
          type: integer
          example: 100
        cpu:
          description: Target average of CPU utilization over running replicas (e.g. 95 means 95%)
          type: integer
          example: 95
          minimum: 0
          maximum: 100
        memory:
          description: Target average of memory utilization over running replicas (e.g. 80 means 80%)
          type: integer
          example: 80
          minimum: 0
          maximum: 100
        rps:
          description: Target average of HTTP requests per seconds over running replicas (e.g. 100 means 100 req/s)
          type: integer
          example: 100
          minimum: 0
        schedules:
          description: Schedules are recurring or not time-windows where the instance can scale in/out regardless of traffic or resource utilization.
          type: array
          items:
            $ref: "#/components/schemas/ScheduledWindow"
        behavior:
          description: Behavior for the autoscale
          $ref: "#/components/schemas/Behavior"
      required:
      - minReplicas
      - maxReplicas

    Behavior:
      type: object
      properties:
        scaleDown:
          description: "how the autoscale should scale down"
          $ref: "#/components/schemas/ScaleDown"

    BindApp:
      type: object
      properties:
        app-name:
          type: string
          example: app1
        app-host:
          type: string
          example: app1.tsuru.example.com
        user:
          type: string
        eventid:
          type: string
        app-hosts:
          type: array
          items:
            type: string
            example: app1.tsuru.example.com
        app-internal-hosts:
          type: array
          items:
            type: string
            example: localService.namespace

    Block:
      type: object
      properties:
        block_name:
          type: string
          enum:
          - root
          - http
          - server
          - lua-server
          - lua-worker
          example: root
        content:
          type: string
          example: |-
            # Some custom Nginx conf snippet which will be injected into root/main context.
            # See more at https://nginx.org/en/docs/ngx_core_module.html
            load_module /path/to/my/module.so;

    CertificateInfo:
      type: object
      properties:
        name:
          type: string
          example: default
        dnsNames:
          type: array
          items:
            type: string
          example:
          - my-instance.example.com
          - my-instance.test
        publicKeyAlgorithm:
          type: string
          enum:
          - ECDSA
          - RSA
          example: RSA
        publicKeyBitSize:
          type: number
          example: 4096
        validFrom:
          type: string
          format: date-time
          example: '2020-08-20T00:00:00Z'
        validUntil:
          type: string
          format: date-time
          example: '2020-08-20T00:00:00Z'

    CreateInstance:
      type: object
      required:
      - name
      - plan
      - team
      properties:
        name:
          type: string
          example: my-instance
          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
          minLength: 1
          maxLength: 30
        plan:
          type: string
          example: small
        team:
          type: string
          example: team-one
        description:
          type: string
          example: Awesome description about an instance.
        tags:
          type: array
          items:
            type: string
            example:
            - tag1
            - tagN
        parameters:
          type: object
          description: |-
            This object must be encoded like [github.com/ajg/form](https://github.com/ajg/form) does. Example:
            ```
            parameters.flavors=chocolate,milk&parameters.ip=169.254.254.100
            ```
          properties:
            flavors:
              type: string
              example: chocolate,milk
            ip:
              type: string
              example: 169.254.254.100
            plan-override:
              type: string
              example: '{"image": "my.registry.test/nginx:v1.18.0"}'
            lb-name:
              type: string
              example: my-instance.custom.example.com

    Error:
      type: object
      properties:
        Msg:
          type: string
          example: instance "my-instance" not found
      required:
      - Msg

    Flavor:
      type: object
      properties:
        name:
          type: string
          example: chocolate
        description:
          type: string
          example: Awesome description about "chocolate" flavor.

    InstanceInfo:
      type: object
      properties:
        name:
          type: string
          example: my-instance
        description:
          type: string
          example: Awesome description about my-instance.
        team:
          type: string
          example: team-one
        tags:
          type: array
          items:
            type: string
          example:
          - tag1
          - tag2
        plan:
          type: string
          example: small
        flavors:
          type: array
          items:
            type: string
          example:
          - coffe
          - milk
          - chocolate
        replicas:
          type: number
          example: 42
        autoscale:
          $ref: '#/components/schemas/Autoscale'
        pods:
          type: array
          items:
            $ref: '#/components/schemas/PodInfo'
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/CertificateInfo'
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/Block'
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'

    Plan:
      type: object
      properties:
        name:
          type: string
          example: small
        description:
          type: string
          example: |-
            Description about "small" plan:
            CPUs: 2 + Memory: 1024MB + Disk: SSD M.2 ultra fast
        schemas:
          type: object
          properties:
            service_instance:
              type: object
              properties:
                create:
                  type: object
                  properties:
                    properties:
                      type: object
                update:
                  type: object
                  properties:
                    properties:
                      type: object
            service_binding:
              type: object
              properties:
                create:
                  type: object
                  properties:
                    properties:
                      type: object
                    response:
                      type: object
          example:
            service_instance:
              create:
                '$id': https://example.com/schema.json
                '$schema': https://json-schema.org/draft-07/schema#
                type: object
                properties:
                  flavors:
                    type: string
                  ip:
                    type: string
                  plan-override:
                    type: string
                  lb-name:
                    type: string

    PodInfo:
      type: object
      properties:
        name:
          type: string
          example: my-instance-abcdef-12345
        ip:
          type: string
          example: 172.16.10.10
        host:
          type: string
          example: 10.10.10.10
        ports:
          type: array
          items:
            $ref: '#/components/schemas/PodPortInfo'
        createdAt:
          type: string
          format: date-time
          example: '2020-08-20T00:00:00Z'

    PodPortInfo:
      type: object
      properties:
        name:
          type: string
          example: http
        hostPort:
          type: number
          example: 20001
        containerPort:
          type: number
          example: 20001
        protocol:
          type: string
          example: TCP
        hostIP:
          type: string
          example: 0.0.0.0

    Purge:
      type: object
      properties:
        path:
          type: string
          example: http/v1/product/catalog.json
        preserve_path:
          type: boolean
          example: true
        extra_headers:
          type: string
          example: '{"accept": "image/jpeg,image/webp"}'

    PurgeBulkResponse:
      type: object
      properties:
        path:
          type: string
          example: http/v1/product/catalog.json
        instances_purged:
          type: integer
          example: 2
        error:
          type: string
          example: "Error trying purge cache."

    Route:
      type: object
      properties:
        path:
          type: string
          example: /checkout/cart
        destination:
          type: string
          example: checkout.apps.tsuru.example.com
        https_only:
          type: boolean
          example: true
        content:
          type: string
          example: ""

    ScaleDown:
      type: object
      properties:
        stabilizationWindowSeconds:
          description: "is the number of seconds for which past recommendations should be considered while scaling up or scaling down."
          type: integer
          example: 300
        unitsPolicyValue:
          description: "set a policy with (value: unitsPolicyValue, type: Pods, periodSeconds: 60s)"
          type: integer
          example: 3
        percentPolicyValue:
          description: "set a policy with (value: percentPolicyValue, type: Percent, periodSeconds: 60s)"
          type: integer
          example: 30

    ScheduledWindow:
      type: object
      properties:
        minReplicas:
          type: integer
          description: Min number of running pods while this window is active.
          example: 10
        start:
          type: string
          description: An Cron expression defining the start of the scheduled window.
          example: "00 20 * * * 1-5"
        end:
          type: string
          description: An Cron expression defining the end of the scheduled window.
          example: "00 00 * * * 1-5"
        timezone:
          type: string
          description: Timezone is a zone name registered on IANA time zone database, default is UTC.
          example: "America/Sao_Paulo"
      required:
      - minReplicas
      - start
      - end

    UpdateInstance:
      type: object
      properties:
        team:
          type: string
          example: team-one
        description:
          type: string
          example: Awesome description about an instance.
        tags:
          type: array
          items:
            type: string
            example:
            - tag1
            - tagN
        parameters:
          type: object
          description: |-
            This object must be encoded like [github.com/ajg/form](https://github.com/ajg/form) does. Example:
            ```
            parameters.flavors=chocolate,milk&parameters.ip=169.254.254.100
            ```
          properties:
            flavors:
              type: string
              example: chocolate,milk
            ip:
              type: string
              example: 169.254.254.100
            plan-override:
              type: string
              example: '{"image": "my.registry.test/nginx:v1.18.0"}'
            lb-name:
              type: string
              example: my-instance.custom.example.com