Server

Easily turns webmiddle applications into REST APIs, allowing remote access via HTTP or WebSocket.

Install

yarn webmiddle-server

Usage

Given some routes that map paths to services, create a server listening on port 3000:

import Server from "webmiddle-server";
import { rootContext } from "webmiddle";

const textResource = (content, name = "result") => rootContext.createResource(
  name,
  "text/plain",
  content
);

const server = new Server({
  "math/multiply": ({ a, b }) => textResource(a * b),
  "math/divide": ({ a, b }) => textResource(a / b))
}, {
  port: 3000,
  apiKey: "justAnyStringHere012",
  contextOptions: { networkRetries: 2 }, // default context options
});
server.start();

How it works

Endpoints can be called by using both GET, POST or WEBSOCKET requests.

Authorization

  • GET/POSTS requests: set an Authorization header with the apiKey as value.
  • WEBSOCKET requests: set an authorization message property with the apiKey as value.

NOTE: if no apiKey option is set when creating the server, then the empty string '' is used.

GET requests:

Input:

  • The query parameters are used as service props.
  • There is no way to pass context options.

Output:

  • In case of success, the output is stringified and sent as application/json.
  • In case of error, a 500 http status code is returned, with the error message as response body.

POST requests:

Input: in this case you explicitly need to pass a JSON object in the request body, composed of the following properties:

  • props: the properties to pass to the service.
  • options: an optional object containing the context options to use.

Output: same as GET requests.

WEBSOCKET requests:

The request is a message with the following format:

{ type: 'request', requestId, authorization, path, body }
  • requestId is an unique identifier for the request, must be generated by the client with libraries such as uuid.
  • authorization the server api key.
  • path: the request endpoint.
  • body: the request body, as in POST requests.

As the request is being evaluated, the server could send progress messages with the following format:

{ type: 'progress', requestId, status, body }
  • status: the topic of the progress message
  • body: the data of the progress message

In case of success, the server will eventually send a message with the following format:

{ type: 'response', requestId, status: 'success', body }
  • body: the response body as stringified json.

In case of error, the server will instead send a message with the following format:

{ type: 'response', requestId, status: 'error', body }
  • body: the error message.

Services

Endpoint: /services/

Lists all the service paths by returning an application/json resource whose content is an array of objects with the following format

{ name, description }

where name and description are the name and description properties of each registered service.

Endpoint: /services/(path)

Executes the service at path (if any) with the provided props and options.
In case of success, the response body will always be a stringified resource.
If the evaluated output isn't already a resource, then such output will be wrapped into a resource having the x-webmiddle-any contentType.

It also creates an evaluation object that can be inspected and controlled by using the dedicated endpoint.

loadMore

Endpoint: /loadMore/(path?):

Lazy load serialized data that was omitted in the progress messages of the services endpoint.
See serialize.js

Evaluations

Endpoint: /evaluations/

Lists all the evaluations by returning an application/json resource whose content is an array of serialized evaluations.

Endpoint: /evaluations/(path)

Controls the evaluation whose id equals to path by using the command specified at props.command:

  • reattach: start getting back response/progress messages of the service that is being evaluated.
  • remove: remove the evaluation.
← PreviousNext →