Home

vs-rest-api wiki

{
    "rest.api": {
        "autoStart": true,
        "openInBrowser": true,
        
        "guest": {
            "isActive": false
        },

        "users": [
            {
                "name": "mkloubert",
                "password": "P@sswort123!"
            },
            {
                "name": "jlpicard",
                "password": "NCC-1701-D"
            },
            {
                "name": "neo",
                "password": "Follow_the_white_rabbit"
            }
        ]
    }
}

Name	Description
`autoStart`	Start HTTP on startup or not. Default: `(false)`
`customOnly`	Indicates if build-in endpoints are disabled by default or not. Default: `(false)`
`disableNewVersionPopups`	Disables popups that report for a new (installed) version. Default: `(false)`
`endpoints`	One or more custom endpoints.
`globals`	Global data for scripts, e.g.
`guest`	Settings for the guest account. This can also be a boolean value that indicates if the account should be active or not. Default: `(false)`
`hooks`	One or more hook to define. s. Hooks
`lang`	The ID of the language to use, like `en` or `de`, otherwise the editor's language is used.
`openInBrowser`	Indicates if the root endpoint should be opened in browser after host has been started or not. Default: `(false)`
`port`	The TCP port the HTTP server should listen on. If this value is an objects, its property names will be used as machine names by using the property values as TCP port, like `{ "MACHINE_1": 1781, "MACHINE_2": 1782 }`. Default: `1781`
`preparer`	The path to a script that can be used for preparing user objects before they are used in an API. s. Preparers
`realm`	The name of the realm for the basic authentification. Default: `REST API for Visual Studio Code (vs-rest-api)`
`showPopupOnSuccess`	Indicates if an info popup / notification should be displayed after a successful start / stop of the API host. Default: `8true)`
`ssl`	Settings for setup secure HTTP.
`users`	One or more user to define.
`validator`	A path to a script that validates the user / connection. s. Validators
`whiteboard`	Settings for a virtual whiteboard. Default: `(true)` (whiteboard is active)
`withDot`	Show (directories) with leading '.' character all accounts or not. Default: `(false)`

SSL [↑]

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)`

Users and guests [↑]

Name	Description
`canActivate`	Defines if account is able to activate extensions or not. Default: `(false)`
`canAnything`	Defines if account is able to do anything with the API or not. Default: `(false)`
`canClose`	Defines if account is able to close editor tabs or not. Default: `(false)`
`canCreate`	Defines if account is able to create things like output channels or not. Default: `(false)`
`canDelete`	Defines if account is able to activate extensions or not. Default: `(false)`
`canDeploy`	Defines if account is able to deploy files or not. Default: `(false)`
`canExecute`	Defines if account is able to execute commands or not. Default: `(false)`
`canOpen`	Defines if account is able to open an editor tab in VS Code or not. Default: `(false)`
`canWrite`	Defines if account has write access or not. Default: `(false)`
`customOnly`	Indicates if build-in endpoints are disabled for that account or not. Default: `(false)`
`endpoints`	If defined: A whitelist of one or more endpoint(s), defined by regular expressions, which are available for the user / guest.
`exclude`	One or more glob pattern that defines what files are NOT visible for this user / guest.
`files`	One or more glob pattern that defines what files are visible for this user / guest.
`isActive`	Is account active or not. Default: `(true)`
`values`	Custom values for the account.
`withDot`	Show (directories) with leading '.' character for the account or not. Default: `(false)`

User / guest endpoints [↑]

Name	Description
`isAvailable`	Endpoint is available or not. Default: `(true)`
`methods`	A list of one or more HTTP methods that are allowed for the user. Default: all

Build-in endpoints [↑]

Name	Description
/api/appglobals	Accesses permanent data for all users outside the current workspace.
/api/appstate	Accesses permanent data for the current user / guest outside the current workspace.
/api/commands	Accesses commands.
/api/cron	Accesses cron jobs.
/api/deploy	Accesses features to deploy files.
/api/editor	Accesses resources of the active editor (tab).
/api/editors	Accesses resources of all opened editors.
/api/extensions	Accesses resources of all known extensions.
/api/files	Accesses resources for handling file operations.
/api/globals	Accesses permanent data for all users.
/api/html	Accesses resources for handling HTML documents.
/api/languages	Accesses resources of all known languages.
/api/outputs	Accesses resources of output channels handled by the extension.
/api/popups	Accesses resources for handling popup messages.
/api/state	Accesses permanent data for the current user / guest.
/api/whiteboard	Accesses resources for handling a virtual whiteboard.
/api/workspace	Accesses or manipulates resources, like files or folders, inside the current workspace.

/api/appglobals [↑]

Accesses permanent data for all users outside the current workspace.

Method	Path	Description
DELETE	/api/appglobals/{name}	Deletes a value.
GET	/api/appglobals	Returns all values.
PUT	/api/appglobals/{name}	Saves a value.

/api/appstate [↑]

Accesses permanent data for the current user / guest outside the current workspace.

Method	Path	Description
DELETE	/api/appstate/{name}	Deletes a value.
GET	/api/appstate	Returns all values.
PUT	/api/appstate/{name}	Saves a value.

/api/commands [↑]

Accesses commands.

Method	Path	Description
GET	/api/commands	Gets a list of available commands.
POST	/api/commands/{command}	Executes a command.

/api/cron [↑]

Accesses cron jobs.

Method	Path	Description
DELETE	/api/cron(/{name})	Stops a cron job.
GET	/api/cron	Gets a list of all cron jobs.
POST	/api/cron(/{name})	Starts a non-running cron job.
PUT	/api/cron(/{name})	(Re-)Starts a cron job.

/api/deploy [↑]

Accesses features to deploy files.

Method	Path	Description
GET	/api/deploy	Returns a list of all deploy targets.
POST	/api/deploy/{file}	Deploys a file.

/api/editor [↑]

Accesses resources of the active editor (tab).

Method	Path	Description
DELETE	/api/editor	Closes / hides the active editor (tab).
GET	/api/editor	Gets the active editor.
PATCH	/api/editor	Updates the content of the active editor.
POST	/api/editor(/{file})	Opens an empty tab or a tab for a file inside the workspace.
PUT	/api/editor	Saves the "dirty" / unsaved content of the active editor (tab).

/api/editors [↑]

Accesses resources of all opened editors.

Method	Path	Description
DELETE	/api/editors(/{id})	Closes / hides an editor (tab).
GET	/api/editors	Gets all opened editors.
PATCH	/api/editors(/{id})	Updates the content of an editor.
POST	/api/editors(/{id})	Sets an editor (tab) on focus.
PUT	/api/editors(/{id})	Saves the "dirty" / unsaved content of an editor (tab).

/api/extensions [↑]

Accesses resources of all known extensions.

Method	Path	Description
GET	/api/extensions	Gets all known extensions.
POST	/api/extensions/{id}	Activates an extension.

/api/files [↑]

Accesses resources for handling file operations.

Method	Path	Description
POST	/api/files	Searches for files inside the workspace.

/api/globals [↑]

Accesses permanent data for all users.

Method	Path	Description
DELETE	/api/globals/{name}	Deletes a value.
GET	/api/globals	Returns all values.
PUT	/api/globals/{name}	Saves a value.

/api/html [↑]

Method	Path	Description
POST	/api/html	Opens a new HTML document (tab) in editor.

/api/languages [↑]

Accesses resources of all known languages.

Method	Path	Description
GET	/api/languages	Lists all known languages.

/api/outputs [↑]

Accesses resources of output channels handled by the extension.

Method	Path	Description
DELETE	/api/outputs/{id}	Deletes an output channel.
GET	/api/outputs	Gets all output channels handled by the extension.
POST	/api/outputs/{name}	Creates a new output channel.
PATCH	/api/outputs/{id}	Overwrites the content of an output channel.
PUT	/api/outputs/{id}	Appends content to an output channel.

/api/popups [↑]

Accesses resources for handling popup messages.

Method	Path	Description
POST	/api/popups	Shows a popup in the editor.

/api/state [↑]

Accesses permanent data for the current user / guest.

Method	Path	Description
DELETE	/api/state/{name}	Deletes a value.
GET	/api/state	Returns all values.
PUT	/api/state/{name}	Saves a value.

/api/whiteboard [↑]

Accesses resources for handling a virtual whiteboard.

Method	Path	Description
DELETE	/api/whiteboard	Deletes the whiteboard and all its revisions.
GET	/api/whiteboard(/{revision})	Gets the current (or a specific) revision of the whiteboard.
POST	/api/whiteboard	Resets the whiteboard with a new document.
PUT	/api/whiteboard	Adds a new revision of a document to the whiteboard.

/api/workspace [↑]

Accesses or manipulates resources, like files or folders, inside the current workspace.

Method	Path	Description
DELETE	/api/workspace/{path}	Deletes a file or folder inside the workspace.
GET	/api/workspace(/{path})	Lists a directory or returns the content of a file inside the workspace.
PATCH	/api/workspace/{path}	Updates an existing file inside the workspace.
POST	/api/workspace/{path}	Creates a new file inside the workspace.
PUT	/api/workspace/{path}	Saves the submitted content to a file inside the workspace.

Custom endpoints [↑]

You can define custom endpoints that are executed via script.

Define one ore more regular expressions in your settings and the scripts that should be executed, if a pattern matches:

{
    "rest.api": {
        // ...
        
        "endpoints": {
            "myendpoint": {
                "script": "./my-endpoint.js",
                "options": "Hello!"
            }
        }
    }
}

The ./my-endpoint.js must contain a public function with the name of the current HTTP request method (upper case).

For example if you want to make a simple GET request

GET /api/myendpoint

your script should look like this:

exports.GET = function(args) {
    // access VS Code API (s. https://code.visualstudio.com/Docs/extensionAPI/vscode-api)
    var vscode = require('vscode');
    
    // access Node.js API provided by VS Code
    // s.  (s. https://nodejs.org/api/)
    var fs = require('fs');
    
    // access an own module
    var myModule = require('./my-module.js');
    
    // access a module used by the extension:
    // s. https://mkloubert.github.io/vs-rest-api/modules/_helpers_.html
    var helpers = args.require('./helpers');
    // s. https://mkloubert.github.io/vs-rest-api/modules/_host_helpers_.html
    var hostHelpers = args.require('./host/helpers');
    
    // access a module that is part of the extentsion
    // s. https://github.com/mkloubert/vs-rest-api/blob/master/package.json
    var glob = args.require('glob');
    
    // access the data from the settings
    // from the example above this is: "Hello!"
    var opts = args.options;
    
    // share / store data (while current session)...
    // ... for this script
    var myState = args.state;
    args.state = new Date();
    // ... with other scripts of this type
    args.globalState['myEndpoint'] = new Date();
    // ... with the whole workspace
    args.workspaceState['myEndpoint'] = new Date();
    
    // if you want to return an AJAX response object:
    // s. https://mkloubert.github.io/vs-rest-api/interfaces/_contracts_.apiresponse.html
    {
        args.response.code = 666;  // the response code (not the HTTP response code!)
        args.response.msg = 'Result of the evil!';  // a custom message for more information
        args.response.data = {
            'mk': 23979,
            'TM': '5979'
        };
    }
    
    // if you want to return custom content
    // instead of the object in 'args.response'
    // s. https://mkloubert.github.io/vs-rest-api/interfaces/_contracts_.apimethodarguments.html#setcontent
    {
        var html = fs.readFileSync('/path/to/my/file.html');
    
        args.setContent(html, 'text/html');
    }
    
    // custom HTTP status code
    args.statusCode = 202;

    // ...
}

The args parameter of the function uses the ApiMethodArguments interface.

You can return a Promise for async executions or nothing for sync executions (as in this example).

You are also able to define functions for other request methods, like POST or DELETE, which are supported by http / https modules of Node.js:

// [DELETE]  /api/myendpoint
exports.DELETE = function(args) {
    return new Promise(function(resolve, reject) {
        // for async executions
        
        try {
            // ...
        
            resolve();  // MUST be called at the end
                        // on SUCCESS
        }
        catch (e) {
            reject(e);  // MUST be called at the end
                        // on ERROR
        }
    });
}

// [POST]  /api/myendpoint
exports.POST = function(args) {
    // no (promise) result means: sync execution
}

HINT: Custom endpoints will always overwrite build-in ones!

Documentation [↑]

The full documentation of the extension's API can be found here.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly