reana_server.json

{
  "definitions": {},
  "info": {
    "description": "Submit workflows to be run on REANA Cloud",
    "title": "REANA Server",
    "version": "0.1"
  },
  "parameters": {},
  "paths": {
    "/api/ping": {
      "get": {
        "description": "Ping the server.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Ping succeeded. Service is running and accessible.",
            "examples": {
              "application/json": {
                "message": "OK",
                "status": 200
              }
            },
            "schema": {
              "properties": {
                "message": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          }
        },
        "summary": "Ping the server (healthcheck)"
      }
    },
    "/api/users": {
      "get": {
        "description": "Get user information.",
        "operationId": "get_user",
        "parameters": [
          {
            "description": "Not required. The email of the user.",
            "in": "query",
            "name": "email",
            "required": false,
            "type": "string"
          },
          {
            "description": "Not required. UUID of the user.",
            "in": "query",
            "name": "id_",
            "required": false,
            "type": "string"
          },
          {
            "description": "Not required. API key of the admin.",
            "in": "query",
            "name": "user_token",
            "required": false,
            "type": "string"
          },
          {
            "description": "Required. API key of the admin.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Users matching criteria were found. Returns all stored user information.",
            "examples": {
              "application/json": [
                {
                  "access_token": "Drmhze6EPcv0fN_81Bj-nA",
                  "email": "user@reana.info",
                  "id": "00000000-0000-0000-0000-000000000000"
                },
                {
                  "access_token": "Drmhze6EPcv0fN_81Bj-nB",
                  "email": "user2@reana.info",
                  "id": "00000000-0000-0000-0000-000000000001"
                }
              ]
            },
            "schema": {
              "items": {
                "properties": {
                  "access_token": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "id_": {
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "type": "array"
            }
          },
          "403": {
            "description": "Request failed. The incoming payload seems malformed."
          },
          "404": {
            "description": "Request failed. User does not exist.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 does not exist."
              }
            }
          },
          "500": {
            "description": "Request failed. Internal server error.",
            "examples": {
              "application/json": {
                "message": "Error while querying."
              }
            }
          }
        },
        "summary": "Get user information. Requires the admin api key."
      },
      "post": {
        "description": "This resource creates a new user with the provided information (email, id). Requires the admin api key.",
        "operationId": "create_user",
        "parameters": [
          {
            "description": "Required. The email of the user.",
            "in": "query",
            "name": "email",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. API key of the user.",
            "in": "query",
            "name": "user_token",
            "required": false,
            "type": "string"
          },
          {
            "description": "Required. API key of the admin.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "201": {
            "description": "User created successfully. Returns the access_token and a message.",
            "examples": {
              "application/json": {
                "access_token": "Drmhze6EPcv0fN_81Bj-nA",
                "email": "user@reana.info",
                "id_": "00000000-0000-0000-0000-000000000000"
              }
            },
            "schema": {
              "properties": {
                "access_token": {
                  "type": "string"
                },
                "email": {
                  "type": "string"
                },
                "id_": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          },
          "403": {
            "description": "Request failed. The incoming payload seems malformed."
          },
          "500": {
            "description": "Request failed. Internal server error.",
            "examples": {
              "application/json": {
                "message": "Internal server error."
              }
            }
          }
        },
        "summary": "Creates a new user with the provided information."
      }
    },
    "/api/workflows": {
      "get": {
        "description": "This resource return all current workflows in JSON format.",
        "operationId": "get_workflows",
        "parameters": [
          {
            "description": "Required. The API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Request succeeded. The response contains the list of all workflows.",
            "examples": {
              "application/json": [
                {
                  "created": "2018-06-13T09:47:35.66097",
                  "id": "256b25f4-4cfb-4684-b7a8-73872ef455a1",
                  "name": "mytest-1",
                  "status": "running",
                  "user": "00000000-0000-0000-0000-000000000000"
                },
                {
                  "created": "2018-06-13T09:47:35.66097",
                  "id": "3c9b117c-d40a-49e3-a6de-5f89fcada5a3",
                  "name": "mytest-2",
                  "status": "finished",
                  "user": "00000000-0000-0000-0000-000000000000"
                },
                {
                  "created": "2018-06-13T09:47:35.66097",
                  "id": "72e3ee4f-9cd3-4dc7-906c-24511d9f5ee3",
                  "name": "mytest-3",
                  "status": "created",
                  "user": "00000000-0000-0000-0000-000000000000"
                },
                {
                  "created": "2018-06-13T09:47:35.66097",
                  "id": "c4c0a1a6-beef-46c7-be04-bf4b3beca5a1",
                  "name": "mytest-4",
                  "status": "created",
                  "user": "00000000-0000-0000-0000-000000000000"
                }
              ]
            },
            "schema": {
              "items": {
                "properties": {
                  "created": {
                    "type": "string"
                  },
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "user": {
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "type": "array"
            }
          },
          "400": {
            "description": "Request failed. The incoming payload seems malformed."
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. User does not exist.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 does not exist."
              }
            }
          },
          "500": {
            "description": "Request failed. Internal controller error.",
            "examples": {
              "application/json": {
                "message": "Something went wrong."
              }
            }
          }
        },
        "summary": "Returns list of all current workflows in REANA."
      },
      "post": {
        "consumes": [
          "application/json"
        ],
        "description": "This resource is expecting a REANA specification in JSON format with all the necessary information to instantiate a workflow.",
        "operationId": "create_workflow",
        "parameters": [
          {
            "description": "Name of the workflow to be created. If not provided name will be generated.",
            "in": "query",
            "name": "workflow_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Remote repository which contains a valid REANA specification.",
            "in": "query",
            "name": "spec",
            "required": false,
            "type": "string"
          },
          {
            "description": "REANA specification with necessary data to instantiate a workflow.",
            "in": "body",
            "name": "reana_spec",
            "required": false,
            "schema": {
              "type": "object"
            }
          },
          {
            "description": "Required. The API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "201": {
            "description": "Request succeeded. The workflow has been created.",
            "examples": {
              "application/json": {
                "message": "The workflow has been successfully created.",
                "workflow_id": "cdcf48b1-c2f3-4693-8230-b066e088c6ac",
                "workflow_name": "mytest-1"
              }
            },
            "schema": {
              "properties": {
                "message": {
                  "type": "string"
                },
                "workflow_id": {
                  "type": "string"
                },
                "workflow_name": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          },
          "400": {
            "description": "Request failed. The incoming payload seems malformed"
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. User does not exist.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 does not exist."
              }
            }
          },
          "500": {
            "description": "Request failed. Internal controller error."
          },
          "501": {
            "description": "Request failed. Not implemented."
          }
        },
        "summary": "Creates a new workflow based on a REANA specification file."
      }
    },
    "/api/workflows/{workflow_id_or_name}/logs": {
      "get": {
        "description": "This resource reports the status of a workflow. Resource is expecting a workflow UUID.",
        "operationId": "get_workflow_logs",
        "parameters": [
          {
            "description": "Required. API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. Analysis UUID or name.",
            "in": "path",
            "name": "workflow_id_or_name",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Request succeeded. Info about a workflow, including the status is returned.",
            "examples": {
              "application/json": {
                "logs": "<Workflow engine log output>",
                "user": "00000000-0000-0000-0000-000000000000",
                "workflow_id": "256b25f4-4cfb-4684-b7a8-73872ef455a1",
                "workflow_name": "mytest-1"
              }
            },
            "schema": {
              "properties": {
                "logs": {
                  "type": "string"
                },
                "user": {
                  "type": "string"
                },
                "workflow_id": {
                  "type": "string"
                },
                "workflow_name": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          },
          "400": {
            "description": "Request failed. The incoming data specification seems malformed.",
            "examples": {
              "application/json": {
                "message": "Malformed request."
              }
            }
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. User does not exist.",
            "examples": {
              "application/json": {
                "message": "Workflow cdcf48b1-c2f3-4693-8230-b066e088c6ac does not exist"
              }
            }
          },
          "500": {
            "description": "Request failed. Internal controller error."
          }
        },
        "summary": "Get workflow logs of a workflow."
      }
    },
    "/api/workflows/{workflow_id_or_name}/status": {
      "get": {
        "description": "This resource reports the status of a workflow. Resource is expecting a workflow UUID.",
        "operationId": "get_workflow_status",
        "parameters": [
          {
            "description": "Required. Analysis UUID or name.",
            "in": "path",
            "name": "workflow_id_or_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. The API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Request succeeded. Info about a workflow, including the status is returned.",
            "examples": {
              "application/json": {
                "created": "2018-06-13T09:47:35.66097",
                "id": "256b25f4-4cfb-4684-b7a8-73872ef455a1",
                "name": "mytest-1",
                "status": "created",
                "user": "00000000-0000-0000-0000-000000000000"
              }
            },
            "schema": {
              "properties": {
                "created": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "logs": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "progress": {
                  "type": "object"
                },
                "status": {
                  "type": "string"
                },
                "user": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          },
          "400": {
            "description": "Request failed. The incoming payload seems malformed.",
            "examples": {
              "application/json": {
                "message": "Malformed request."
              }
            }
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. Either User or Analysis does not exist.",
            "examples": {
              "application/json": {
                "message": "Analysis 256b25f4-4cfb-4684-b7a8-73872ef455a1 does not exist."
              }
            }
          },
          "500": {
            "description": "Request failed. Internal controller error."
          }
        },
        "summary": "Get status of a workflow."
      },
      "put": {
        "consumes": [
          "application/json"
        ],
        "description": "This resource reports the status of a workflow. Resource is expecting a workflow UUID.",
        "operationId": "set_workflow_status",
        "parameters": [
          {
            "description": "Required. Analysis UUID or name.",
            "in": "path",
            "name": "workflow_id_or_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. New workflow status.",
            "in": "query",
            "name": "status",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. The API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          },
          {
            "description": "Optional. Extra parameters for workflow status.",
            "in": "body",
            "name": "parameters",
            "required": false,
            "schema": {
              "type": "object"
            }
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Request succeeded. Info about a workflow, including the status is returned.",
            "examples": {
              "application/json": {
                "id": "256b25f4-4cfb-4684-b7a8-73872ef455a1",
                "message": "Workflow successfully launched",
                "status": "created",
                "user": "00000000-0000-0000-0000-000000000000",
                "workflow_name": "mytest-1"
              }
            },
            "schema": {
              "properties": {
                "message": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "user": {
                  "type": "string"
                },
                "workflow_id": {
                  "type": "string"
                },
                "workflow_name": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          },
          "400": {
            "description": "Request failed. The incoming payload seems malformed.",
            "examples": {
              "application/json": {
                "message": "Malformed request."
              }
            }
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. Either User or Workflow does not exist.",
            "examples": {
              "application/json": {
                "message": "Workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1 does not exist"
              }
            }
          },
          "409": {
            "description": "Request failed. The workflow could not be started due to a conflict.",
            "examples": {
              "application/json": {
                "message": "Workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1 could not be started because it is already running."
              }
            }
          },
          "500": {
            "description": "Request failed. Internal controller error."
          },
          "501": {
            "description": "Request failed. The specified status change is not implemented.",
            "examples": {
              "application/json": {
                "message": "Status resume is not supported yet."
              }
            }
          }
        },
        "summary": "Set status of a workflow."
      }
    },
    "/api/workflows/{workflow_id_or_name}/workspace": {
      "get": {
        "description": "This resource retrieves the file list of a workspace, given its workflow UUID.",
        "operationId": "get_files",
        "parameters": [
          {
            "description": "Required. Analysis UUID or name.",
            "in": "path",
            "name": "workflow_id_or_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. The API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Requests succeeded. The list of files has been retrieved.",
            "schema": {
              "items": {
                "properties": {
                  "last-modified": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "size": {
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "type": "array"
            }
          },
          "400": {
            "description": "Request failed. The incoming payload seems malformed."
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. Analysis does not exist.",
            "examples": {
              "application/json": {
                "message": "Analysis 256b25f4-4cfb-4684-b7a8-73872ef455a1 does not exist."
              }
            }
          },
          "500": {
            "description": "Request failed. Internal server error.",
            "examples": {
              "application/json": {
                "message": "Internal server error."
              }
            }
          }
        },
        "summary": "Returns the workspace file list."
      },
      "post": {
        "consumes": [
          "multipart/form-data"
        ],
        "description": "This resource is expecting a file to place in the workspace.",
        "operationId": "upload_file",
        "parameters": [
          {
            "description": "Required. Analysis UUID or name.",
            "in": "path",
            "name": "workflow_id_or_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. File to be transferred to the workflow workspace.",
            "in": "formData",
            "name": "file_content",
            "required": true,
            "type": "file"
          },
          {
            "description": "Required. File name.",
            "in": "query",
            "name": "file_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. The API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Request succeeded. File successfully transferred.",
            "schema": {
              "properties": {
                "message": {
                  "type": "string"
                }
              },
              "type": "object"
            }
          },
          "400": {
            "description": "Request failed. The incoming payload seems malformed"
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. User does not exist.",
            "examples": {
              "application/json": {
                "message": "Workflow cdcf48b1-c2f3-4693-8230-b066e088c6ac does not exist"
              }
            }
          },
          "500": {
            "description": "Request failed. Internal server error.",
            "examples": {
              "application/json": {
                "message": "Internal server error."
              }
            }
          }
        },
        "summary": "Adds a file to the workspace."
      }
    },
    "/api/workflows/{workflow_id_or_name}/workspace/{file_name}": {
      "get": {
        "description": "This resource is expecting a workflow UUID and a file name existing inside the workspace to return its content.",
        "operationId": "download_file",
        "parameters": [
          {
            "description": "Required. workflow UUID or name.",
            "in": "path",
            "name": "workflow_id_or_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. Name (or path) of the file to be downloaded.",
            "in": "path",
            "name": "file_name",
            "required": true,
            "type": "string"
          },
          {
            "description": "Required. The API access_token of workflow owner.",
            "in": "query",
            "name": "access_token",
            "required": true,
            "type": "string"
          }
        ],
        "produces": [
          "multipart/form-data"
        ],
        "responses": {
          "200": {
            "description": "Requests succeeded. The file has been downloaded.",
            "schema": {
              "type": "file"
            }
          },
          "400": {
            "description": "Request failed. The incoming payload seems malformed."
          },
          "403": {
            "description": "Request failed. User is not allowed to access workflow.",
            "examples": {
              "application/json": {
                "message": "User 00000000-0000-0000-0000-000000000000 is not allowed to access workflow 256b25f4-4cfb-4684-b7a8-73872ef455a1"
              }
            }
          },
          "404": {
            "description": "Request failed. `file_name` does not exist .",
            "examples": {
              "application/json": {
                "message": "input.csv does not exist"
              }
            }
          },
          "500": {
            "description": "Request failed. Internal server error.",
            "examples": {
              "application/json": {
                "message": "Internal server error."
              }
            }
          }
        },
        "summary": "Returns the requested file."
      }
    }
  },
  "swagger": "2.0",
  "tags": []
}