swagger: '2.0'
info:
  description: |
    The Visual Flow Creator (VFC) API service can be used to create, update, retrieve and delete projects and nodes which belong to projects. It also supports triggering nodes of type `inject` which means that users can directly start flows using the API.

    ## Generic Errors

    The following generic error codes (with status codes) can occur at the operations of this API. Generic error codes are prefixed with 'mdsp.core.generic.'.

    - missingParameter (400)
    - invalidParameter (400)
    - missingRequestBodyProperty (400)
    - invalidRequestBodyProperty (400)
    - unauthorized (401)
    - forbidden (403)
    - noMatch (412)
    - unsupportedMediaType (415)
    - tooManyRequests (429)
    - internalServerError (500)

    See the Insights Hub Developer Documentation generic errors page for more information on these errors.

    ## VFC API Errors

    The following error codes (with status codes) may occur when executing API requests. These error codes are prefixed with 'mdsp.core.vfc.'.

    - bodyShouldBeAnArray (400)
    - validationError (400)
    - noUserGiven (400)
    - noBodyGiven (400)
    - noNodeIdGiven (400)
    - tabsLimitExceeded (400)
    - nodesLimitExceeded (400)
    - forbiddenToReadFlows (403)
    - forbiddenToSaveFlows (403)
    - forbiddenToTriggerFlows (403)
    - projectNotFound (404)
    - nodeNotFound (404)
    - nodeNotTypeOfInject (404)
    - notAllowed (405)
    - foundDuplicatedEndpoint (409)

    See the Insights Hub Visual Flow Creator Documentation for more information on these errors.

    Visual Flow Create Documentation is available here: https://documentation.mindsphere.io/MindSphere/apis-xcelerator/advanced-visual-flow-creator/api-visual-flow-creator-overview.html

  version: '3.0.0'
  title: VFC API
  x-visibility: 'external'
basePath: /api/vfc/v3
schemes:
  - https
securityDefinitions:
  vfc:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      vfc.api.r: read nodes
      vfc.api.w: write nodes
      vfc.api.t: trigger inject nodes
tags:
  - name: 'projects'
    description: Projects management
  - name: 'nodes'
    description: Nodes management
  - name: 'trigger'
    description: Flows triggering
paths:
  /projects:
    get:
      tags:
        - projects
      summary: Reads all projects of the specified user
      description: Returns a list of projects of the given user. If no user is specified, an error will be returned.
      produces:
        - application/json
      security:
        - vfc:
          - vfc.api.r
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the impersonated token.
          required: true
          type: string
      responses:
        '200':
          description: A list of projects
          schema:
            $ref: '#/definitions/Projects'
        '400':
          description: The user id is missing
          schema:
            $ref: '#/definitions/NoUserGivenError'
    post:
      tags:
        - projects
      summary: Create new project
      description: |
        Creates a project with the provided project name.

        If no `name` is given in the request, then an error will be returned. The `userId` parameter is required. The name `default` is not allowed to be used.
      consumes:
        - application/json
      produces:
        - application/json
      security:
        - vfc:
          - vfc.api.w
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the impersonated token.
          required: true
          type: string
        - name: name
          in: body
          description: Name of the project
          required: true
          schema:
            $ref: '#/definitions/ProjectName'
      responses:
        '201':
          description: The project has been created successfully
          schema:
            $ref: '#/definitions/Project'
        '400':
          description: |
            Bad request
            An HTTP 400 error can occur if
            - the project name is missing
            - the project name is not supported (the name 'default' is not supported)
          schema:
            $ref: '#/definitions/CreateProject400Error'
        '409':
          description: Project already exists conflict
          schema:
            $ref: '#/definitions/ProjectAlreadyExistsError'
  /projects/{id}:
    get:
      tags:
        - projects
      summary: Read the project
      description: |
        Read the specified project information belonging to the specified user. The project information consists of the id, name, user and tenant. To get the nodes which belong to the project, use the "nodes" endpoint
      produces:
        - application/json
      security:
        - vfc:
          - vfc.api.r
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the impersonated token.
          required: true
          type: string
        - name: id
          in: path
          description: id of a project
          required: true
          type: string
      responses:
        '200':
          description: The project information
          schema:
            $ref: '#/definitions/Project'
        '400':
          description: The user id is missing
          schema:
            $ref: '#/definitions/NoUserGivenError'
        '404':
          description: The project does not exist
          schema:
            $ref: '#/definitions/ProjectNotFoundError'

    patch:
      tags:
        - projects
      summary: Rename a project
      description: Update the project properties of the project with project id `id` and user `user`. Currently only the `name` property can be updated (so currently PATCH can be used to rename projects).
      consumes:
        - application/json
      produces:
        - application/json
      security:
        - vfc:
          - vfc.api.w
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the impersonated token.
          required: true
          type: string
        - name: id
          in: path
          description: id of a project
          required: true
          type: string
        - name: name
          in: body
          required: true
          schema:
            $ref: '#/definitions/ProjectName'
      responses:
        '200':
          description: Project has been successfully renamed
          schema:
            $ref: '#/definitions/Project'
        '400':
          description: Cannot rename 'default' project
          schema:
            $ref: '#/definitions/CannotChangeDefaultProjectError'
    delete:
      tags:
        - projects
      summary: Delete a project
      description: Delete the project with id `id` and user `userId`
      consumes:
        - application/json
      produces:
        - text/plain
      security:
        - vfc:
          - vfc.api.w
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the impersonated token.
          required: true
          type: string
        - name: id
          in: path
          description: id of a project
          required: true
          type: string
      responses:
        '204':
          description: Project has been deleted successfully
        '404':
          description: |
            The request will return a 400 Project not found in the case when the project id submitted in the request does not reference an existing project.
          schema:
            $ref: '#/definitions/ProjectNotFoundError'
  /projects/{id}/nodes:
    get:
      tags:
        - nodes
      summary: Read project's nodes
      description: |
        Read all nodes of the specified project. After getting the nodes you can inspect them, import them into new projects (see `PUT` endpoint) or transfer them to a different tenant.
      produces:
        - application/json
      security:
        - vfc:
          - vfc.api.r
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the user impersonated token.
          required: true
          type: string
        - name: id
          in: path
          description: id of the project
          required: true
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Nodes'
        '404':
          description: Project not found. This error gets returned if the project is not found
          schema:
            $ref: '#/definitions/ProjectNotFoundError'
    put:
      tags:
        - nodes
      summary: Create or replace flow nodes
      description: Create nodes or replace existing nodes belonging to a project with new nodes. When executing this request, all existing nodes of the project will be removed. All the nodes included in the request will be added to the project.
      consumes:
        - application/json
      produces:
        - text/plain
        - application/json
      security:
        - vfc:
          - vfc.api.w
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the impersonated token.
          required: true
          type: string
        - name: id
          in: path
          description: id of the project
          required: true
          type: string
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/NodesArray'
      responses:
        '200':
          description: The nodes have been added to the project
        '404':
          description: Project not found
          schema:
            $ref: '#/definitions/ProjectNotFoundError'
        '400':
          description: |
            Bad request
            An HTTP 400 error can occur if
            - no body is included in the request
            - the body is not an array
            - the body cannot be validated
            - other common errors occur
            If a required parameter is not included or in a wrong format, an HTTP 400 error will be returned
          schema:
            $ref: '#/definitions/PutNodes400Error'
        '409':
          description: Nodes contain already http-in node with already existing endpoint (in other tenant's project) or multiple http-in nodes with same endpoint
          schema:
            $ref: '#/definitions/FoundDuplicatedEndpointError'
  /projects/{id}/nodes/{nodeId}/trigger:
    post:
      tags:
        - trigger
      summary: Starts a flow
      description: When calling this endpoint with a node id of a node of type `inject`, this inject node gets triggered and starts the flow. Subsequent nodes of the inject node will receive the message created by the inject node and can again send messages to subsequent nodes.
      produces:
        - text/plain
        - application/json
      security:
        - vfc:
          - vfc.api.t
      parameters:
        - name: userId
          in: query
          description: The id of the user. Usually this is the user's email address. If this parameter does not exist the API tries to extract it from the impersonated token.
          required: true
          type: string
        - name: id
          in: path
          description: id of the project
          required: true
          type: string
        - name: nodeId
          in: path
          description: id of the inject node
          required: true
          type: string
        - name: body
          description: The message to be send
          in: body
          required: true
          schema:
            $ref: '#/definitions/TriggerNode'
      responses:
        '200':
          description: Success
        '404':
          description: |
            Not found
            An HTTP 404 (resource not found) error can occur if
              - the project is not found
              - the node is not found
          schema:
            $ref: '#/definitions/TriggerNode404Error'
        '400':
          description:  |
            Bad request
            An HTTP 400 error can occur if
              - some parameter is missing
              - the node is not of type "inject"
              - other common error
          schema:
            $ref: '#/definitions/TriggerNode400Error'
definitions:
  ProjectNotFoundError:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.projectNotFound"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Project not found"
  TriggerNode404Error:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.projectNotFound"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Project not found"
  ProjectAlreadyExistsError:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.projectAlreadyExists"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Project already exists"
  CreateProject400Error:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.projectNameRequired"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Project name required"
  PutNodes400Error:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.validationError"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Validation error"
  CannotChangeDefaultProjectError:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.errorChangingDefaultProject"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Cannot change default project"
  NoUserGivenError:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.noUserGiven"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "No user given"
  TriggerNode400Error:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.nodeNotTypeOfInject"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Node not type of inject"
  FoundDuplicatedEndpointError:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            code:
              type: string
              example: "mdsp.core.vfc.foundDuplicatedEndpoint"
            logref:
              type: string
              example: "0bff7e7acd25457699084180ef086174"
            message:
              type: string
              example: "Found duplicated HTTP-IN endpoint"
  Projects:
    type: object
    properties:
      projects:
        type: array
        items:
          $ref: '#/definitions/Project'
  Project:
    type: object
    properties:
      id:
        type: string
        example: zXehuYJOP-F4fhZ4VyCRG&EIO
      name:
        type: string
        example: Production line 1
      userId:
        type: string
        example: user@example.com
      tenant:
        type: string
        example: myiottenant
  ProjectName:
    type: object
    properties:
      name:
        type: string
        example: Production line 1
  Nodes:
    type: object
    properties:
      nodes:
        $ref: '#/definitions/NodesArray'
  NodesArray:
    type: array
    items:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
      additionalProperties:
        type: string
        description: |
          Depending on the type of the node further properties must be provided to define the node properly.
    example: [
      {
        "id": "1118462b.66faca",
        "type": "tab",
        "label": "Flow 1",
        "disabled": false,
        "info": ""
      },
      {
        "id": "47efc38e.1cf96c",
        "type": "inject",
        "z": "1118462b.66faca",
        "name": "",
        "topic": "",
        "payload": "",
        "payloadType": "date",
        "repeat": "",
        "repeatEnd": "0",
        "endTime": "0",
        "crontab": "",
        "offset": "0",
        "once": false,
        "properties": "",
        "timezone": "utc",
        "betweentimesunit": "m",
        "enableRuleEngine": false,
        "showNextExecution": false,
        "powerMode": false,
        "x": 153.5,
        "y": 102,
        "wires": [
          [
            "adef7e63.67a72"
          ]
        ]
      },
      {
        "id": "adef7e63.67a72",
        "type": "debug",
        "z": "1118462b.66faca",
        "name": "",
        "active": true,
        "console": "false",
        "xaxis": "_time",
        "complete": "false",
        "x": 425.5,
        "y": 104,
        "wires": []
      }
    ]
  TriggerNode:
    type: object
    properties:
      payload:
        type: object
      topic:
        type: string
    example: {
      "topic":"MyTopic",
      "payload":1660739931990,
      "_msgid":"8d015cc1.c4418","_starttime":1660739931990
}