Skip to content
This repository has been archived by the owner on Aug 31, 2021. It is now read-only.

apis

Jump to bottom
Marcel Kloubert edited this page Mar 26, 2018 · 27 revisions

Home >> Settings >> APIs

APIs

The extension can run one more REST API hosts.

This can be useful, if something should control an editor from remote, e.g. a build operation, which runs on a server, shows a popup, when its done.

A list of endpoints (with examples) can be found here.

{
    "deploy.reloaded": {
        "apis": {
            "80": {
                "allowed": [
                    "192.168.0.0/24",
                    "0:0:0:0:0:ffff:c0a8:0/24"
                ],

                "users": {
                    "mkloubert": "P@ssword123!"
                }
            }
        }
    }
}

Settings

Name Description
allowed One or more allowed IP addresses in CIDR format.
autoStart Auto start host or not. Default: (true)
description* A description for the host.
endpoints A list of one or more custom endpoints to define.
name* A (display) name for the host.
realm* The custom name of the real for basic authentification. Default: vscode-deploy-reloaded API
ssl Settings for secure HTTP.
useBuildIn Use build-in endpoints or not. Default: (true)
users One or more user to define.

* supports placeholders

SSL

{
    "deploy.reloaded": {
        "apis": {
            "443": {
                "ssl": {
                    "cert": "./cert.pem",
                    "key": "./key.pem"
                }
            }
        }
    }
}
Name Description
ca* The path to the ca file.
cert* The path to the file of the certificate.
key* The path to the key file.
passphrase The required password for the key file.
rejectUnauthorized Request unauthorized or not. Default: (true)

* supports placeholders

Relative paths are mapped to the .vscode folder or the sub folder .vscode-deploy-reloaded inside the user's home directory.

Users

{
    "deploy.reloaded": {
        "apis": {
            "443": {
                "users": {
                    "mk": "P@assword!123",
                    "tm": {
                        "password": "@notherPassword123!"
                    }
                }
            }
        }
    }
}
Name Description
isActive Is user active or not. Default: (true)
password The password to use.

Endpoints

[GET] /api

Returns general information.

Request

GET /api HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: application/json; charset=utf-8
Content-Length: 324
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

{
  "success": true,
  "code": 0,
  "host": {
    "os": "win32"
  },
  "me": {
    "address": "::ffff:127.0.0.1",
    "port": 5979
  },
  "message": "OK",
  "vscode": {
    "eol": "\r\n",
    "name": "Visual Studio Code",
    "node": {
      "v8": "5.8.283.38",
      "version": "7.9.0"
    },
    "version": "1.21.1"
  }
}

[GET] /api/commands

Returns a list of all commands.

Request

GET /api/commands HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: application/json; charset=utf-8
Content-Length: 120
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": [
    "editor.action.selectAll",
    "git.pull"    
  ]
}

[POST] /api/commands/:command

Executes a command.

Request

GET /api/commands/editor.action.selectAll HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 204 No Content
X-Powered-By: Express
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

[GET] /api/editors

Returns a list of all editors.

Request

GET /api/editors HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: application/json; charset=utf-8
Content-Length: 233
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": [
    {
      "index": 0,
      "isActive": true,
      "document": {
        "eol": "\r\n",
        "file": {
          "name": "ltotm.txt",
          "path": "c:\\my-project"
        },
        "isDirty": false,
        "isUntitled": false,
        "language": "jsonc",
        "lines": 39,
        "resources": {
          "_self": "/api/editors/0",
          "content": "/api/editors/0/content"
        },
        "version": 1
      }
    }
  ]
}

[POST] /api/editors

Opens a new text editor (with content).

Request

POST /api/editors HTTP/1.1
Host: localhost

Lorem ipsum

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: application/json; charset=utf-8
Content-Length: 277
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": {
    "index": 0,
    "isActive": true,
    "document": {
      "eol": "\r\n",
      "file": {
        "name": "Untitled-1"
      },
      "isDirty": true,
      "isUntitled": true,
      "language": "json",
      "lines": 4,
      "resources": {
        "_self": "/api/editors/0",
        "content": "/api/editors/0/content"
      },
      "version": 1
    }
  }
}

[GET] /api/editors/:index

Returns information about an editor.

Request

GET /api/editors/0 HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: application/json; charset=utf-8
Content-Length: 231
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": {
    "index": 0,
    "isActive": true,
    "document": {
      "eol": "\n",
      "file": {
          "name": "ltotm.txt",
          "path": "/home/mkloubert/my-project"
      },
      "isDirty": false,
      "isUntitled": false,
      "language": "jsonc",
      "lines": 39,
      "resources": {
        "_self": "/api/editors/0",
        "content": "/api/editors/0/content"
      },
      "version": 1
    }
  }
}

[GET] /api/editors/:index/content

Returns the content of an editor.

Request

GET /api/editors/0/content HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: text/plain; charset=utf-8
X-Vscode-Deploy-Reloaded-Lang: plaintext
Content-Length: 889
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

[GET] /api/extensions

Returns a list of all extensions.

Request

GET /api/extensions HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: application/json; charset=utf-8
Content-Length: 11790
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": [
    {
      "id": "bmewburn.vscode-intelephense-client",
      "index": 0,
      "isActive": false,
      "path": "C:\\Users\\houbi\\.vscode\\extensions\\bmewburn.vscode-intelephense-client-0.8.8"
    },
    {
      "id": "christian-kohler.path-intellisense",
      "index": 1,
      "isActive": true,
      "path": "C:\\Users\\houbi\\.vscode\\extensions\\christian-kohler.path-intellisense-1.4.2"
    }
  ]
}

[GET] /api/languages

Returns a list of all languages.

Request

GET /api/languages HTTP/1.1
Host: localhost

Possible reponse

HTTP/1.1 200 OK
X-Powered-By: Express
Content-type: application/json; charset=utf-8
Content-Length: 598
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": [
    "csharp"
    "typescript"
    "xml"
  ]
}

[POST] /api/markdown

Opens a new tab of a parsed Markdown document.

Request

POST /api/markdown HTTP/1.1
Host: localhost

{
    "title": "My Document",
    "content": "# Header 1\n\nLorem ipsum",

    "options": {
        "css": "body { background-color: red; }"
    }
}

Reponse

HTTP/1.1 204 No Content
X-Powered-By: Express
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

[POST] /api/messages

Shows a popup in the remote editor.

Request

POST /api/messages HTTP/1.1
Host: localhost

{
    "message": "Test message",
    "type": "error"
}

Possible values for type, which is optional, are:

  • e, err, error
  • i, info, information
  • w, warn, warning

Response

HTTP/1.1 204 No Content
X-Powered-By: Express
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

[PUT] /api/output

Writes text to the output channel of the extension.

Request

PUT /api/output HTTP/1.1
Host: localhost

Lorem ipsum

Response

HTTP/1.1 204 No Content
X-Powered-By: Express
Date: Wed, 5 Sep 1979 23:09:00 GMT
Connection: keep-alive

Custom endpoints

{
    "deploy.reloaded": {
        "apis": {
            "80": {
                "endpoints": {
                    "my_endpoint": {
                        "methods": [ "GET", "POST" ],
                       
                        "script": "./api.my_endpoint.js",
                        "options": 5979
                    }
                }
            }
        }
    }
}
Name Description
methods A list of one or more allowed HTTP methods. Default: all
options Options for the script.
script The path to the script to execute. Relative paths will be mapped to the .vscode subfolder or the .vscode-deploy-reloaded folder inside the user's home directory.

The endpoint in the upper example will be available via /api/my_endpoint. Have a look at the article Routing to get to known, how to define routes via Express.

The script ./api.my_endpoint.js should look like that:

exports.GET = async function(args, request, response) {
    response.setHeader('Content-type', 'application/json; charset=utf-8');

    return response.status(200).send(new Buffer(
        JSON.stringify({
            'test': 23979 + args.options
        }),
        'utf8'
    ));
};

exports.POST = async function(args, request, response) {
    const Helpers = args.require('./helpers');

    const BODY = await Helpers.readAll( request );

    // TODO

    return response.status(204)
                   .send();
};

Each HTTP method is handled by a public / exported function, with the name of the method in upper case.

If you want to handle any (other) HTTP method, you have to implement a request() function:

exports.request = async function(args, request, response) {
    // HTTP method is stored in 'request.method'
};

args implements the ApiEndpointArguments interface.

request and response parameters are the same, as defined in the Express API.

Clone this wiki locally