{
  "openapi": "3.0.0",
  "info": {
    "title": "REST4i - IFS Services",
    "description": "Integrated File System (IFS) Services provide APIs for accessing objects in a way that is like personal computer and UNIX operating systems. This includes listing objects in directories, reading from files, and writing to files.",
    "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": "IFS Services",
      "description": "Integrated File System (IFS) Services provide APIs for accessing objects in a way that is like personal computer and UNIX operating systems."
    }
  ],
  "paths": {
    "/v1/ifs/{path}": {
      "get": {
        "tags": ["IFS Services"],
        "summary": "Get the content of a file.",
        "description": "Get the content of a file. The content is returned in a JSON object.",
        "operationId": "ifsGetFileContent",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization HTTP header.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ETag",
            "in": "header",
            "description": "Whether to return checksum for the file.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "path",
            "in": "path",
            "description": "Path to file for which the data is to be read.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request.",
            "content": {
              "application/json": {
                "example": {
                  "ccsid": 819,
                  "content": "Hello world\n"
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "404": {
            "description": "The specified resource was not found.",
            "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": []
          },
          {
            "basicHttpAuthentication": []
          }
        ]
      },
      "put": {
        "tags": ["IFS Services"],
        "summary": "Write a string to a file.",
        "description": "Write a string to a file. The file must exist and its contents will be replaced by the string specified in the request.",
        "operationId": "ifsPutFileContent",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization HTTP header.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "description": "If the If-Match HTTP header is passed, RSE API will check to see if the Etag (MD5 hash of the object content) matches the provided Etag value. If this value matches, the operation will proceed. If the match fails, the system will return a 412 (Precondition Failed) error.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "path",
            "in": "path",
            "description": "Path to file in which the data will be written.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "File content.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/rest4i_FileContent"
              },
              "example": {
                "content": "some data that will be written to file."
              }
            },
            "text/plain": {
              "schema": {},
              "example": "some data that will be written to file.\n"
            }
          },
          "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"
                }
              }
            }
          },
          "404": {
            "description": "The specified resource was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "412": {
            "description": "Precondition failed."
          },
          "500": {
            "description": "Unable to process the request due to an internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerHttpAuthentication": []
          },
          {
            "basicHttpAuthentication": []
          }
        ]
      }
    },
    "/v1/ifs/list": {
      "get": {
        "tags": ["IFS Services"],
        "summary": "Gets a list of objects in the specified path.",
        "description": "Gets a list of objects in the specified path. The information returned includes the name, whether object is a directory, the description, and the object subtype. For objects that are not in the QSYS.LIB file system, any part of the path may contain an asterisk (*), which is a wildcard that means zero or more instances of any character.",
        "operationId": "ifsListDir",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization HTTP header.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "path",
            "in": "query",
            "description": "The working directory. For example, /u/IBM/test",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subtype",
            "in": "query",
            "description": "Subtype of objects to return. Valid values include a specific object type (*LIB, *FILE, *PGM, *OUTQ, etc.) or *ALL.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "includehidden",
            "in": "query",
            "description": "Whether to show hidden files.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request.",
            "content": {
              "application/json": {
                "example": {
                  "objects": [
                    {
                      "path": "/QSYS.LIB/USER1.LIB/QCLSRC.FILE",
                      "description": "\"test\"",
                      "isDir": true,
                      "subType": "PF-SRC"
                    },
                    {
                      "path": "/QSYS.LIB/USER1.LIB/QCSRC.FILE",
                      "description": "",
                      "isDir": true,
                      "subType": "PF-SRC"
                    }
                  ]
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "404": {
            "description": "The specified resource was not found.",
            "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": []
          },
          {
            "basicHttpAuthentication": []
          }
        ]
      }
    },
    "/v1/ifs/{path}/info": {
      "get": {
        "tags": ["IFS Services"],
        "summary": "Returns information about the object referenced by the path.",
        "description": "Returns information about the object referenced by the path. The information returned includes the name, whether object is a directory, the description, the object subtype, CCSID, size, last modified timestamp, and object subtype.",
        "operationId": "ifsGetFileInfo",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization HTTP header.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "path",
            "in": "path",
            "description": "Path to object for which information is to be returned.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request.",
            "content": {
              "application/json": {
                "example": {
                  "path": "/qsys.lib/user1.lib",
                  "description": "user1's lib",
                  "isDir": true,
                  "subType": "PROD",
                  "owner": "USER1",
                  "ccsid": 37,
                  "lastModified": 1680559633,
                  "size": 401408,
                  "recordLength": -1,
                  "numberOfRecords": -1
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "404": {
            "description": "The specified resource was not found.",
            "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": []
          },
          {
            "basicHttpAuthentication": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "rest4i_FileContent": {
        "required": ["content"],
        "type": "object",
        "properties": {
          "content": {
            "type": "string"
          }
        },
        "description": "The file content."
      },
      "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"
      }
    }
  }
}
