From 33522ffba209b9114102e000dcc5399481e925ce Mon Sep 17 00:00:00 2001 From: Kevin Powick Date: Thu, 11 Jun 2020 12:24:06 -0400 Subject: [PATCH] Re-introduce accidentally deleted /doc files --- doc/DeveloperIntro.md | 5 + doc/MV REST File System API.md | 1080 +++++++++++++++++ ...V REST File System.postman_collection.json | 336 +++++ 3 files changed, 1421 insertions(+) create mode 100644 doc/MV REST File System API.md create mode 100644 doc/MV REST File System.postman_collection.json diff --git a/doc/DeveloperIntro.md b/doc/DeveloperIntro.md index ccc08d7..417947b 100644 --- a/doc/DeveloperIntro.md +++ b/doc/DeveloperIntro.md @@ -19,6 +19,7 @@ - [3.1.3 Code Formatting](#313-code-formatting) - [3.1.4 Intellisense](#314-intellisense) - [3.1.5 Code Snippets](#315-code-snippets) + - [3.2 MV REST File System](#32-mv-rest-file-system) - [4. Syntax definitions / theming](#4-syntax-definitions--theming) - [4.1 Resources](#41-resources) - [4.2 Changing/Adding Scopes](#42-changingadding-scopes) @@ -171,6 +172,10 @@ Hovering over a statement or function, or pressing Ctrl+Space, will provide a "t ### 3.1.5 Code Snippets Code snippets are user-defined short-cuts that can be used for any commonly repeated set of keystrokes. For example, you could type "prog" or "sub", Ctrl+Space, and a standard code header could be inserted, and prompts for the variable parts filled in. They are not part of the extension, but depending on what you have loaded in snippets, can confuse tooltops and command completion. +## 3.2 MV REST File System + +The MVBasic extension includes its own File System Provider which provides access to the MV file system. The MV REST File System API is documented [here](MV%20REST%20File%20System%20API.md). Currently, the AccuTerm RestFS Connector implements this API. Other implementations are welcome. + [(top)](#table-of-contents) # 4. Syntax definitions / theming diff --git a/doc/MV REST File System API.md b/doc/MV REST File System API.md new file mode 100644 index 0000000..96bab02 --- /dev/null +++ b/doc/MV REST File System API.md @@ -0,0 +1,1080 @@ +## **Login** +---- + Call the login API to authorize subsequent API functions. The login API may return an authorization token to be used in subsequent calls. + +* **URL** + + `/login` + +* **Method:** + + `POST` + +* **URL Params** + + None + +* **Data Params** + + ``` + { + "ServerIP": RemoteHost, + "ServerType": GatewayType, + "ServerName": ServerName, + "UserId": UserName, + "Password": Password, + "AccountName": Account, + "AccountPath": AccountPath, + "AccountPassword": AccountPassword, + "Client": "vscode.restfs" + } + ``` + +* **Success Response:** + * **Code:** 200 OK + * **Content:** +``` +{ + "token_type": "Bearer", + "access_token": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiIxIn0=" +} +``` + If an authorization token is returned, it should be used in subsequent calls in the 'authorization' header. + + +* **Error Response:** + + * **Code:** 500 Internal Error + * **Content:** +``` +{ + "status": 500, + "message": "Session is not running FTSERVER program", + "code": "1027" +} +``` + +* OR + + * **Code:** 401 Unauthorized + * **Content:** +``` +{ + "status": 401, + "message": "Unable to authenticate", + "code": "1028" +} +``` + +* **Sample Call:** +``` +curl --location --request POST 'http://localhost:3181/mvsvr/restfs/login' \ +--header 'Accept: application/json' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "ServerName": "@12345", + "Account": "ACCUTERM8", + "Client": "vscode.restfs" +}' +``` + +* **Notes:** + + For MVGateway login parameter details, refer to the mvextensions.mvbasic gateway settings: +[https://github.com/mvextensions/mvbasic/blob/master/doc/Extension%20Guide.md#7-sample-settings-files](https://github.com/mvextensions/mvbasic/blob/master/doc/Extension%20Guide.md#7-sample-settings-files). + + For AccuTerm RestFS Connector, include these properties: +``` +{ + "ServerName": , + "Account": , + "Client": "vscode.restfs" +} +``` + Error codes and messages shown here are only examples. Actual codes and message text are an implementation detail. + + ## **Logout** +---- + Call the logout API to terminate the login session. The logout API must include the authorization token returned by the login API in the authroization header. + +* **URL** + + `/logout` + +* **Method:** + + `GET` + +* **URL Params** + + None + +* **Data Params** + + None + +* **Success Response:** + * **Code:** 200 OK + + +* **Sample Call:** +``` +curl --location --request GET 'http://localhost:3181/mvsvr/restfs/logout' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiIyIn0=' +``` + +* **Notes:** + + For AccuTerm RestFS Connector, the logout API will end the FTSERVER session. + +## **Read Directory** +---- + Call the read directory API to read the contents of a directory. + +* **URL** + + `/dir////` + +* **Method:** + + `GET` + +* **URL Params** + + \ + + The account where the file is to be read from. + + \/\/\ + + The location of the directory within the account. Note that for MultiValue databases supporting this REST File System API, \/\/\ may be mapped to MV items in the MD or VOC of the account, a dictionary file or a data file. + + ?attr=&max_items= + + Attributes is a bitmask used to limit the items returned. max_items is the maximum number of items to return. + +* **Data Params** + + None + +* **Success Response:** + * **Code:** 200 OK + * **Content:** +``` +{ + "items": [ + { + "id": , + "attr": , + "size": + }, ... + ] +} +``` + Each line of the file is returned as an element of the data array. + +* **Error Response:** + + * **Code:** 500 Internal Error + * **Content:** +``` +{ + "status": 500, + "message": "Session is not running FTSERVER program", + "code": "1027" +} +``` + +* OR + + * **Code:** 401 Unauthorized + * **Content:** +``` +{ + "status": 401, + "message": "Authorization token must be included in the Authorization header" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file name missing", + "code": "200" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file not found", + "code": "201" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "item not found", + "code": "202" +} +``` + +* **Sample Call:** + +``` +curl --location --request GET 'http://localhost:3181/mvsvr/restfs/dir/ACCUTERM8/SAMPLES?attr=32976&max_items=250' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiI2In0=' +``` + +* **Notes:** + + Error codes and messages shown here are only examples. Actual codes and message text are an implementation detail. + +## **Read File** +---- + Call the read file API to read the contents of a file. + +* **URL** + + `/file////` + +* **Method:** + + `GET` + +* **URL Params** + + \ + + The account where the file is to be read from. + + \/\/\ + + The location of the file within the account. Note that for MultiValue databases supporting this REST File System API, \/\/\ may be mapped to MV items in the MD or VOC of the account, a dictionary file or a data file. + +* **Data Params** + + None + +* **Success Response:** + * **Code:** 200 OK + * **Content:** +``` +{ + "id": , + "type": "array", + "data": [ + , + , ... + ] +} +``` + Each line of the file is returned as an element of the data array. + +* **Error Response:** + + * **Code:** 500 Internal Error + * **Content:** +``` +{ + "status": 500, + "message": "Session is not running FTSERVER program", + "code": "1027" +} +``` + +* OR + + * **Code:** 401 Unauthorized + * **Content:** +``` +{ + "status": 401, + "message": "Authorization token must be included in the Authorization header" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file name missing", + "code": "200" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file not found", + "code": "201" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "item not found", + "code": "202" +} +``` + +* **Sample Call:** + +``` +curl --location --request GET 'http://localhost:3181/mvsvr/restfs/file/ACCUTERM8/SAMPLES/SAMPLES/NOTEPAD' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiI2In0=' +``` + +* **Notes:** + + For MultiValue systems, each attribute of an item is returned as an element of the data array. If a line (attribute) contains multi-values, the values are returned in a nested array within the attribute element. If a value contains sub-values, the sub-values are returned in a nested array within the value element. In this way, MV delimiters are never returned directly in the API so the API is agnostic to the delimiter values for any MV platform. + + Error codes and messages shown here are only examples. Actual codes and message text are an implementation detail. + +## **Update File** +---- + Call the update file API to write the contents of a file. + +* **URL** + + `/file////` + +* **Method:** + + `PUT` + +* **URL Params** + + \ + + The account where the file is to be written to. + + \/\/\ + + The location of the file within the account. Note that for MultiValue databases supporting this REST File System API, \/\/\ may be mapped to MV items in the MD or VOC of the account, a dictionary file or a data file. + +* **Data Params** + + ``` + { + "id": FileName, + "type": "array", + "data": [ + , + , ... + ] + } + ``` + Each line of the file is sent as an element of the data array. + +* **Success Response:** + * **Code:** 200 OK + * **Content:** + + None + +* **Error Response:** + + * **Code:** 500 Internal Error + * **Content:** +``` +{ + "status": 500, + "message": "Session is not running FTSERVER program", + "code": "1027" +} +``` + +* OR + + * **Code:** 401 Unauthorized + * **Content:** +``` +{ + "status": 401, + "message": "Authorization token must be included in the Authorization header" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file name missing", + "code": "200" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file not found", + "code": "201" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "update failed", + "code": "261" +} + +* **Sample Call:** + +``` +curl --location --request PUT 'http://localhost:3181/mvsvr/restfs/file/ACCUTERM8/SAMPLES/SAMPLES/TESTING' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiI2In0=' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "id": "TESTING", + "type": "array", + "data": [ + "* A Test", + "PRINT '\''Testing'\''", + "END" + ] +}' +``` + +* **Notes:** + + For MultiValue systems, each attribute of an item is sent as an element of the data array. If a line (attribute) contains multi-values, the values are sent in a nested array within the attribute element. If a value contains sub-values, the sub-values are sent in a nested array within the value element. In this way, MV delimiters are never sent directly in the API so the API is agnostic to the delimiter values for any MV platform. + + Error codes and messages shown here are only examples. Actual codes and message text are an implementation detail. + +## **Create File or Directory** +---- + Call the create API to create a new file or directory. + +* **URL** + + `/create////` + +* **Method:** + + `POST` + +* **URL Params** + + \ + + The account where the file is to be written to. + + \/\/\ + + The location of the file or directory within the account. Note that for MultiValue databases supporting this REST File System API, \/\/\ may be mapped to MV items in the MD or VOC of the account, a dictionary file or a data file. Some servers may not allow creating directories (or new files). + + ?dir=true + + When creating a directory (or folder), specify dir=true in the URL query string. + +* **Data Params (ignored when creating a directory)** + + ``` + { + "id": FileName, + "type": "array", + "data": [ + , + ... + ] + } + ``` + Each line of the file is sent as an element of the data array. + +* **Success Response:** + * **Code:** 200 OK + * **Content:** + + None + +* **Error Response:** + + * **Code:** 500 Internal Error + * **Content:** +``` +{ + "status": 500, + "message": "Session is not running FTSERVER program", + "code": "1027" +} +``` + +* OR + + * **Code:** 401 Unauthorized + * **Content:** +``` +{ + "status": 401, + "message": "Authorization token must be included in the Authorization header" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file name missing", + "code": "200" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "creating new directories is not supported" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file not found", + "code": "201" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file or directory exists", + "code": "223" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "update failed", + "code": "261" +} + +* **Sample Call:** + +``` +curl --location --request POST 'http://localhost:3181/mvsvr/restfs/create/ACCUTERM8/SAMPLES/SAMPLES/NEW' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiI2In0=' \ +--header 'Content-Type: application/json' \ +--header 'Content-Type: text/plain' \ +--data-raw '{ + "id": "NEW", + "type": "array", + "data": [ + "* A New Item", + "PRINT '\''Hello'\''", + "END" + ] +}' +``` + +* **Notes:** + + For MultiValue systems, each attribute of an item is sent as an element of the data array. If a line (attribute) contains multi-values, the values are sent in a nested array within the attribute element. If a value contains sub-values, the sub-values are sent in a nested array within the value element. In this way, MV delimiters are never sent directly in the API so the API is agnostic to the delimiter values for any MV platform. + + Error codes and messages shown here are only examples. Actual codes and message text are an implementation detail. + +## **Delete File** +---- + Call the delete file API to delete a file. + +* **URL** + + `/file////` + +* **Method:** + + `DELETE` + +* **URL Params** + + \ + + The account where the file is to be deleted. + + \/\/\ + + The location of the file within the account. Note that for MultiValue databases supporting this REST File System API, \/\/\ may be mapped to MV items in the MD or VOC of the account, a dictionary file or a data file. + +* **Data Params** + + None + +* **Success Response:** + * **Code:** 200 OK + * **Content:** + + None + +* **Error Response:** + + * **Code:** 500 Internal Error + * **Content:** +``` +{ + "status": 500, + "message": "Session is not running FTSERVER program", + "code": "1027" +} +``` + +* OR + + * **Code:** 401 Unauthorized + * **Content:** +``` +{ + "status": 401, + "message": "Authorization token must be included in the Authorization header" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file name missing", + "code": "200" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file not found", + "code": "201" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "item not found", + "code": "202" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "delete failed due to item lock", + "code": "235" +} +``` + +* **Sample Call:** + +``` +curl --location --request DELETE 'http://localhost:3181/mvsvr/restfs/file/ACCUTERM8/SAMPLES/SAMPLES/NEW' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiI2In0=' +``` + +* **Notes:** + + Error codes and messages shown here are only examples. Actual codes and message text are an implementation detail. + +## **Rename File** +---- + Call the rename file API to rename a file or directory. + +* **URL** + + `/rename////` + +* **Method:** + + `GET` + +* **URL Params** + + \ + + The account where the original file is located. + + \/\/\ + + The location of the original file within the account. Note that for MultiValue databases supporting this REST File System API, \/\/\ may be mapped to MV items in the MD or VOC of the account, a dictionary file or a data file. + + ?newname=\/\/\/\ + + The new account, location and name of the file. + +* **Data Params** + + None + +* **Success Response:** + * **Code:** 200 OK + * **Content:** + + None + +* **Error Response:** + + * **Code:** 500 Internal Error + * **Content:** +``` +{ + "status": 500, + "message": "Session is not running FTSERVER program", + "code": "1027" +} +``` + +* OR + + * **Code:** 401 Unauthorized + * **Content:** +``` +{ + "status": 401, + "message": "Authorization token must be included in the Authorization header" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file name missing", + "code": "200" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file not found", + "code": "201" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "item not found", + "code": "202" +} +``` + +* OR + + * **Code:** 400 Bad Request + * **Content:** +``` +{ + "status": 400, + "message": "file or directory exists", + "code": "223" +} +``` + +* **Sample Call:** + +``` +curl --location --request GET 'http://localhost:3181/mvsvr/restfs/rename/ACCUTERM8/SAMPLES/SAMPLES/TESTING?newname=ACCUTERM8/SAMPLES/SAMPLES/NEWTEST' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0=.eyJzaWQiOiI2In0=' +``` + +* **Notes:** + + For AccuTerm RestFS Connector, rename cannot move files to different directories or accounts. Only the file name (MV item ID) may be renamed. + + Error codes and messages shown here are only examples. Actual codes and message text are an implementation detail. + +## **Command** +---- + Execute a command on the server. + +* **URL** + + `/cmd///path>//` + +* **Method:** + + `POST` + +* **URL Params** + + \ + + The command to execute. For MVBasic RestFS, supported commands are 'compile' and 'catalog'. + + \/\/\/\ + + The location of the file passed to the command. Note that for MultiValue databases supporting this REST File System API, \/\/\ may be mapped to MV items in the MD or VOC of the account, a dictionary file or a data file. + +* **Data Params** + + ``` + { +