HTTP API - gd-99/symbiogd GitHub Wiki

In order to communicate with the server, the client sends requests to the server. Currently, HTTP requests and WebSocket are supported.

Sending requests

Each app in the webos is supposed to use built-in functions to communicate with the server. Use the HTTP API only if you're building an external app, not working in Symbiose.

HTTP requests

  • URL: /api
  • Method: POST

WebSockets

URL: /api/ws

Be careful: you'll have to use the port as set in the configuration file.

The WebSocket server now uses WAMP (version 1). In order to be able to talk with the server, you will need a WAMP-compatible WebSocket client. To call the API, you can send a CALL message with call id api.call.

Request data

A request must contain these fields:

  • module: the request's module
  • action: the request's action
  • object arguments: arguments. Must be JSON-encoded and URI-encoded (see urlencode() or encodeURIComponent())

A request can contain these fields too:

  • user: the username which will be used to execute the request
  • password: the user's password (only if user is provided)

Batch HTTP requests

Batching allows you to pass instructions for several operations in a single HTTP request.

  • URL: /api/group
  • Method: POST

Required fields:

  • groupped: must be set to true
  • data: contains a JSON-encoded array of requests

Receiving responses

A response is a JSON-encoded string which contain these fields:

  • boolean success: true if there was no error
  • number statusCode: the response's status code (based on HTTP status codes). 200 is returned if there was no error.
  • object channels: Unix-like standard streams: object containing outputs associated with their channel number (1 for standard output, 2 for standard error).
  • string out: main channel, merges all others
  • object data: object containing plain data

Modules

You must specify a module name in your request. Each request will be processed by a specific controller. These controllers are stored in /lib/ctrl/api.

If you want to call a controller named FileController, the module name will be file. If you want to call a method named executeGetContents, the action name will be getContents.