socketcluster-api
SocketCluster-API is a module for creating REST api's over SocketCluster's websocket implementation.
If you're familiar with expressjs using socketcluster-api
will include many familiar steps
This is built using sc-codec-protobuf
which will
encode all messages using Google Protocol Buffer.
All messages are encoded to a protobuf, which also requires you to provided message definitions.
Getting started
Using the following protobuf for the getting started
syntax = "proto3"; package app; message RequestMessage { string a = 1; string b = 2;} message ResponseMessage { string c = 1;} message SomeError { uint32 code = 1; string message = 2;}
Server
const protobuf = /* acquire protobuf as a string */const API = ;const app = protobuf const router = app; // `data` is provided by the clientrouter; // SocketCluster's workerController { // Get the custom codecEngine so that protobuf message are properly encoded/decoded. scServer; // Register the router for each client that connects scServer;}
Client
;;; const api = protobuf ; const socket = socketCluster; // Makes `get` available as a function on `socket`api; // Calls the `/resource` endpoint, with a message of type `.app.RequestMessage`.// Note that the data must fit the `.app.RequestMessage` or an error will be thrown.socket ;
Advanced topics - Server
Nested routers
const resourceRouter = // 1 ; // 2 const router = // 3 ; // 4 // ... // This will bind the following routes:// 1. '/resource/'// 2. '/resource/something'// 3. '/resource// 4. Doesn't bind anything since handler is a `Router`router;
NB. /resource
and /resource/
(trailing slash) are different routes and invokes different handlers
Routers can be nested to any depth.