{
  "openapi": "3.0.0",
  "info": {
    "title": "REST4i - Session Services",
    "description": "Session Services provide APIs for authenticating a user and managing sessions that are tied to an authenticated user. The user must have a user profile on the IBM i server to be accessed. Once authenticated, a bearer token is returned and must be submitted on requests when invoking protected APIs in an HTTP authorization header.",
    "version": "1.0.7-rest4i",
    "contact": {
      "name": "API Support",
      "url": "https://github.com/rest4i"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "/rest4i/api"
    }
  ],
  "tags": [
    {
      "name": "Session Services",
      "description": "Session Services provide APIs for authenticating a user and managing sessions that are tied to an authenticated user."
    }
  ],
  "paths": {
    "/v1/session": {
      "get": {
        "tags": ["Session Services"],
        "summary": "Get information about the session.",
        "description": "Get information about the session. The information returned includes session settings in addition to information about any host server jobs tied to the session.",
        "operationId": "sessionQuery",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization HTTP header.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "envvars",
            "in": "query",
            "description": "Comma separated list of environment variables to return from the remote command host server job.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "maxjoblogrecords",
            "in": "query",
            "description": "Maximum number of message log records to return from the remote command host server job.",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "joblogfilter",
            "in": "query",
            "description": "Comma separated list of message IDs. Only remote command host server job log messages that do not match the filter message IDs will be returned.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request.",
            "content": {
              "application/json": {
                "example": {
                  "sessionInfo": {
                    "userID": "user1",
                    "host": "localhost",
                    "expiration": "2023-04-04T00:56:35Z",
                    "creation": "2023-04-03T22:04:50Z",
                    "lastUsed": "2023-04-03T22:56:35Z",
                    "domain": "rest4i",
                    "expired": false
                  },
                  "sessionSettings": {
                    "libraryList": [],
                    "clCommands": [],
                    "envVariables": {},
                    "sqlDefaultSchema": null,
                    "sqlTreatWarningsAsErrors": false,
                    "sqlProperties": {},
                    "sqlStatements": []
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request was made.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "The request is forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Unable to process the request due to an internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerHttpAuthentication": []
          }
        ]
      },
      "put": {
        "tags": ["Session Services"],
        "summary": "Refresh session settings.",
        "description": "Refresh session settings. The settings affect the remote command and database host server jobs that are tied to the session. Refreshing session settings may result in the ending of existing host server jobs.",
        "operationId": "sessionRefresh",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization HTTP header.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The settings for the session.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/rest4i_SessionSettings"
              },
              "example": {
                "resetSettings": true,
                "continueOnError": true,
                "libraryList": ["lib1", "lib2"],
                "clCommands": ["QSYS/CLRLIB LIB(BUILD)"],
                "envVariables": {
                  "var1": "var1val",
                  "var2": "var2val"
                },
                "sqlDefaultSchema": "lib1",
                "sqlProperties": {
                  "auto commit": "true",
                  "ignore warnings": "01003,0100C,01567"
                },
                "sqlStatements": ["SET PATH = LIB1, LIB2"]
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Successful request, no content."
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request was made.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "The request is forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Unable to process the request due to an internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerHttpAuthentication": []
          }
        ]
      },
      "post": {
        "tags": ["Session Services"],
        "summary": "Authenticate with user credentials and return an embedded token.",
        "description": "Authenticate with user credentials and return an embedded token to access different RSE APIs. On successful authentication, a token is returned in the Authorization HTTP header. The client must send this token in the Authorization HTTP header when making requests to protected RSE APIs.",
        "operationId": "sessionLogin",
        "requestBody": {
          "description": "The user credentials to be authenticated.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/rest4i_LoginCredentials"
              },
              "example": {
                "host": "localhost",
                "userid": "user",
                "password": "pwd"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful request, new resource created."
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request was made.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "The request is forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Unable to process the request due to an internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Session Services"],
        "summary": "Logout, releasing resources tied to the session.",
        "description": "Logout, releasing resources tied to the session. If a logout is not performed, it will be discarded after a period of idle time (default is 2 hours).",
        "operationId": "sessionLogout",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization HTTP header.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successful request, no content."
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request was made.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "The request is forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Unable to process the request due to an internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerHttpAuthentication": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "rest4i_LoginCredentials": {
        "required": ["password", "userid"],
        "type": "object",
        "properties": {
          "host": {
            "type": "string",
            "description": "The IBM i server from which objects are to be accessed.",
            "default": "localhost"
          },
          "userid": {
            "type": "string",
            "description": "The user ID."
          },
          "password": {
            "type": "string",
            "description": "The password."
          }
        },
        "description": "The login credentials."
      },
      "rest4i_SessionSettings": {
        "type": "object",
        "properties": {
          "resetSettings": {
            "type": "boolean",
            "description": "Replace existing sessions attributes. A value of false will merge settings in request with existing session settings.",
            "default": false
          },
          "continueOnError": {
            "type": "boolean",
            "description": "Continue with session processing if an error occurs.",
            "default": false
          },
          "libraryList": {
            "type": "array",
            "description": "Library to be added to library list of the remote command host server job tied to session.",
            "items": {
              "type": "string"
            }
          },
          "clCommands": {
            "type": "array",
            "description": "CL command to be run in remote command host server job tied to session.",
            "items": {
              "type": "string"
            }
          },
          "envVariables": {
            "type": "object",
            "description": "Environment variable to set in remote command host server job tied to session.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "sqlDefaultSchema": {
            "type": "string",
            "description": "Default SQL schema to use when running SQL statements in database host server job."
          },
          "sqlTreatWarningsAsErrors": {
            "type": "boolean",
            "description": "Treat SQL warnings as errors.",
            "default": false
          },
          "sqlProperties": {
            "type": "object",
            "description": "Java toolbox JDBC property.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "sqlStatements": {
            "type": "array",
            "description": "SQL statement to be run in database host server job tied to session.",
            "items": {
              "type": "string"
            }
          }
        },
        "description": "The settings for the session."
      },
      "Problem": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "format": "int32"
          },
          "details": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerHttpAuthentication": {
        "type": "http",
        "description": "Bearer token authentication.",
        "scheme": "bearer",
        "bearerFormat": "Bearer [token]"
      },
      "basicHttpAuthentication": {
        "type": "http",
        "description": "Basic authentication.",
        "scheme": "basic"
      }
    }
  }
}
