Difference between revisions of "webAPI for softMC"

From SoftMC-Wiki
Jump to: navigation, search
(Blanked the page)
Line 1: Line 1:
 +
=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: <br>
 +
# softMC Web Server
 +
# softMC minimum version: 0.4.17.3
 +
# WebAPI license
 +
 +
=Getting Started=
 +
{{Note| The way to upload and access files to softMC explained [[Basic Web Server|HERE]]}}
 +
==='''Installing the JavaScript library'''===
 +
# Download the JavaScript script which will be provided with your webAPI license, and located it in your project's folder. <br> {{Note|Projects should be located in ''/var/home/mc/www'' }}
 +
# In your HTML file, include conn.js in your ''<head>'' tag: <br>
 +
<syntaxhighlight lang="html4strict">
 +
<head>
 +
    <script src = "js/conn.js"></script>
 +
</head>
 +
</syntaxhighlight>
 +
==='''Connecting to softMC'''===
 +
Use those commands at your project to be able to communicate with softMC: <br>
 +
# To initialize a WebSocket connection: <br>  '''new MC_CONNECTION().init();'''
 +
# 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: <br> '''new MC_CONNECTION(callback).init();'''
 +
# Advanced users who wishes to customize the WebSocket behavior (onopen, onerror, onmessage, onclose…) can open ''conn.js'' and edit the functions there.
 +
==='''Querying softMC'''===
 +
# After initializing the WebSocket connection, you may use the following command to query the controller using MC-Basic syntax: <br> '''conn.queryMC(query,callback);'''
 +
# For example: <br>
 +
<syntaxhighlight lang="javascript">
 +
conn.queryMC(“?ver”,function(result){
 +
    alert(“Your softMC version is “ + result);
 +
});
 +
</syntaxhighlight>
 +
 +
=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.
 +
{{Note/Important| All requests should be done to '''PORT 1207 (!)'''}}
 +
 +
==='''Getting Files List'''===
 +
{|class="wikitable"
 +
|width="150"|'''Description'''
 +
|Get Files
 +
|-
 +
|'''URL'''
 +
|/cs/files
 +
|-
 +
|'''Method'''
 +
|GET
 +
|-
 +
|'''Data Params (optional)'''
 +
|{ext: [string], asJSON: [Boolean]} <br> '''ext:''' A comma-separated list of the extensions you want to get. <br> '''asJSON":''' should the list return as a JSON array? <br> '''<u> Examples:</u>''' <br> {ext:  “PRG,LIB”, asJSON: false} <br> {ext:  “PRG,LIB”, asJSON: true}
 +
|-
 +
|'''Success Response'''
 +
|'''Code:''' 200 <br> '''Content:''' <br> [String of comma-separated files] '''<big><big>or</big></big>''' [JSON Array of files objects] <br> '''<u>Examples:'''</u> <br>1. "AUTOEXEC.PRG,SETUP.PRG,TP.LIB” <br>2. <syntaxhighlight lang=freebasic>[
 +
    {
 +
        fileName:  AUTOEXEC.PRG,
 +
        modified:  1499679189000,
 +
        fileNameOnly:  AUTOEXEC
 +
        extension:  PRG
 +
    }
 +
]
 +
</syntaxhighlight>
 +
|-
 +
|'''Sample Call'''
 +
|<syntaxhighlight lang="html4strict">$.get(“http://” + ip + “:1207/cs/files/”,{asJSON:true},callback);</syntaxhighlight>
 +
|-
 +
|'''Notes'''
 +
|If an error occurs, the file list would be empty
 +
|}
 +
 +
 +
==='''Getting File Content'''===
 +
{|class="wikitable"
 +
|width="150"|'''Description'''
 +
|Get a specific file content
 +
|-
 +
|'''URL'''
 +
|/cs/file/:''filename''
 +
|-
 +
|'''Method'''
 +
|GET
 +
|-
 +
|'''Success Response'''
 +
|'''Code:''' 200 <br> '''Content:''' [String of file content] <br> '''<u>Example:</u>''' <br> “This is the file content\nReturned as a string”
 +
|-
 +
|'''Sample Call'''
 +
|<syntaxhighlight lang="html4strict">$.get(“http://” + ip + “:1207/cs/file/MYFILE.PRG”,function(result){
 +
    console.log(result);
 +
});
 +
</syntaxhighlight>
 +
|-
 +
|'''Notes'''
 +
|If an error occurs, the file content would be empty
 +
|}
 +
 +
==='''Uploading Files - No Overwrit)'''===
 +
{|class="wikitable"
 +
|width="150"|'''Description'''
 +
|Uploading files (Unless the file already exists)
 +
|-
 +
|'''URL'''
 +
|/cs/upload
 +
|-
 +
|'''method'''
 +
|POST
 +
|-
 +
|'''Data (Required)'''
 +
|'''Data Type:''' multipart/from-data <br> '''File Part name:''' file
 +
|-
 +
|'''Success Response'''
 +
|'''code:''' 200 or 403 if permission is denied <br> '''Response Type:''' JSON <br> '''Content:''' <syntaxhighlight lang="html4strict">{
 +
    err: [integer] / undefined
 +
}
 +
</syntaxhighlight> <br> '''Error Codes:''' <br> -1 - File already exist <br> -2 - Unknown Error <br> -3 - Invalid data format sent <br> -4 - Permission denied
 +
|-
 +
|'''Sample Call'''
 +
|<syntaxhighlight lang="html4strict">
 +
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
 +
}
 +
});
 +
 +
</syntaxhighlight>
 +
|}
 +
 +
==='''Uploading Files - Overwrit Existing)'''===
 +
{|class="wikitable"
 +
|width="150"|'''Description'''
 +
|Uploading files and overwrite existing file if exists
 +
|-
 +
|'''URL'''
 +
|/cs/upload/overwrite
 +
|-
 +
|'''method'''
 +
|POST
 +
|-
 +
|'''Data (Required)'''
 +
|'''Data Type:''' multipart/from-data <br> '''File Part name:''' file
 +
|-
 +
|'''Success Response'''
 +
|'''code:''' 200 or 403 if permission is denied <br> '''Response Type:''' JSON <br> '''Content:''' <syntaxhighlight lang="html4strict">{
 +
    err: [integer] / undefined
 +
}
 +
</syntaxhighlight> <br> '''Error Codes:''' <br> -2 - Unknown Error <br> -4 - Permission denied
 +
|-
 +
|'''Sample Call'''
 +
|<syntaxhighlight lang="html4strict">
 +
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
 +
}
 +
});
 +
 +
</syntaxhighlight>
 +
|}

Revision as of 08:02, 21 February 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 Overwrit)

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 - Overwrit 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
}
});
Retrieved from "http://softmc.servotronix.com/index.php?title=webAPI_for_softMC&oldid=132475"