Difference between revisions of "webAPI for softMC"

From SoftMC-Wiki
Jump to: navigation, search
Line 213: Line 213:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
|}
 
|}
 +
 +
 +
=Example=

Revision as of 12:29, 1 March 2018

Introduction

WebAPI allows users to do the following actions from a web-browser:

  • Query softMC – send MC-Basic commands and get a response, async.
  • Upload files – files will be uploaded into /var/home/mc/FFS0/SSMC folder.
  • Get the file list on MC – retrieve a list of the files inside the SSMC folder.
  • Get file content – retrieve the content of a file inside the SSMC folder.


In order to use the Web API, the following should be installed on the softMC:

  1. softMC Web Server
  2. softMC minimum version: 0.4.17.3
  3. WebAPI license

Getting Started

NOTE-Info.svgNOTE
The way to upload and access files to softMC explained HERE

Installing the JavaScript library

  1. Download the JavaScript script which will be provided with your webAPI license, and located it in your project's folder.
    NOTE-Info.svgNOTE
    Projects should be located in /var/home/mc/www
  2. In your HTML file, include conn.js in your <head> tag: 
<head>
    <script src = "js/conn.js"></script>
</head>

Connecting to softMC

Use those commands at your project to be able to communicate with softMC:

  1. To initialize a WebSocket connection:
    new MC_CONNECTION().init();
  2. In case you want a callback to be called once a connection has been made (when the WebSocket’s onopen method is called), you can pass a callback as a parameter like so:
    new MC_CONNECTION(callback).init();
  3. Advanced users who wishes to customize the WebSocket behavior (onopen, onerror, onmessage, onclose…) can open conn.js and edit the functions there.

Querying softMC

  1. After initializing the WebSocket connection, you may use the following command to query the controller using MC-Basic syntax:
    conn.queryMC(query,callback);
  2. For example: 
conn.queryMC(“?ver”,function(result){
    alert(“Your softMC version is “ + result);
});

File Operation

Overview

  • File operations (upload, get content, etc…) can be done using a REST API.
  • It’s best practice to use AJAX to retrieve the data asynchronously.
IMPORTANT.svgIMPORTANT
All requests should be done to PORT 1207 (!)

Getting Files List

Description Get Files
URL /cs/files
Method GET
Data Params (optional) {ext: [string], asJSON: [Boolean]}
ext: A comma-separated list of the extensions you want to get.
asJSON": should the list return as a JSON array?
Examples:
{ext: “PRG,LIB”, asJSON: false}
{ext: “PRG,LIB”, asJSON: true}
Success Response Code: 200
Content:
[String of comma-separated files] or [JSON Array of files objects]
Examples:
1. "AUTOEXEC.PRG,SETUP.PRG,TP.LIB”
2. 
[
    {
        fileName:  AUTOEXEC.PRG,
        modified:  1499679189000,
        fileNameOnly:  AUTOEXEC
        extension:  PRG
    }
]
Sample Call 
$.get(“http://” + ip + “:1207/cs/files/”,{asJSON:true},callback);
Notes If an error occurs, the file list would be empty


Getting File Content

Description Get a specific file content
URL /cs/file/:filename
Method GET
Success Response Code: 200
Content: [String of file content]
Example:
“This is the file content\nReturned as a string”
Sample Call 
$.get(“http://” + ip + “:1207/cs/file/MYFILE.PRG”,function(result){
    console.log(result);
});
Notes If an error occurs, the file content would be empty

Uploading Files - No Overwrite

Description Uploading files (Unless the file already exists)
URL /cs/upload
method POST
Data (Required) Data Type: multipart/from-data
File Part name: file
Success Response code: 200 or 403 if permission is denied
Response Type: JSON
Content: 
{
    err: [integer] / undefined
}

Error Codes:
-1 - File already exist
-2 - Unknown Error
-3 - Invalid data format sent
-4 - Permission denied
Sample Call 
var formData = new FormData();
formData.append('file', new File([new Blob([“content”])], “A.PRG” ));
$.ajax({
contentType: "multipart/form-data;",
url: “http://” + ip + “:1207/cs/upload”,
type: 'POST',
data: formData,
cache: false,
contentType: false,
processData: false,
success: function(result) {
    if (result.err)
        // do something with the error
}
});

Uploading Files - Overwrite Existing

Description Uploading files and overwrite existing file if exists
URL /cs/upload/overwrite
method POST
Data (Required) Data Type: multipart/from-data
File Part name: file
Success Response code: 200 or 403 if permission is denied
Response Type: JSON
Content: 
{
    err: [integer] / undefined
}

Error Codes:
-2 - Unknown Error
-4 - Permission denied
Sample Call 
var formData = new FormData();
formData.append('file', new File([new Blob([“content”])], “A.PRG” ));
$.ajax({
contentType: "multipart/form-data;",
url: “http://” + ip + “:1207/cs/upload/overwrite”,
type: 'POST',
data: formData,
cache: false,
contentType: false,
processData: false,
success: function(result) {
    if (result.err)
        // do something with the error
}
});


Deleting Files

Description Delete a specific file
URL /cs/file/:filename
method DELETE
Success Response code: 200
Content: true/false
Sample Call 
$.ajax({
  url: “http://” + ip + ”:1207/cs/file/MYFILE.PRG”,
  type: 'DELETE',
  success: function(result) {
     if (result) {
          // success
      } else {
          // failed
      }
  }
});


Example

Retrieved from "http://softmc.servotronix.com/index.php?title=webAPI_for_softMC&oldid=132510"