Realtime API Gateway
Synchronize Your Clients
Visit Resgate.io for guides, live demos, and resources.
Resgate is a Go project implementing a realtime API gateway for the RES protocol with NATS server as messaging system.
It is a simple server that lets you create REST, real time, and RPC APIs, where all your clients are synchronized seamlessly.
Used for building new REST APIs with real-time functionality, or when creating single page applications using reactive frameworks such as React, Vue.js, or Modapp.
Screen capture from the Book Collection Example. Try out the Live demo version yourself.
How it works
Resgate handles all API requests from your clients, instead of directly exposing your micro-services (represented by Node.js and Java below). Clients will connect to Resgate, using either HTTP or WebSocket, to make requests. These requests are sent to the micro-services over NATS server, and Resgate will keep track on which resource each client has requested.
Whenever there is a change to the data, the responsible micro-service sends an event. Resgate will use this event to both update its own cache, and make sure each subscribing client is kept up-to-date.
Quickstart
If you install Docker, it is easy to run both NATS server and Resgate as containers:
docker network create res
docker run -d --name nats -p 4222:4222 --net res nats
docker run --name resgate -p 8080:8080 --net res resgateio/resgate --nats nats://nats:4222
Both images are small, about 10 MB each.
See Resgate.io - Installation for other ways of installation.
Examples
While Resgate may be used with any language, the examples in this repository are written in Javascript for Node.js, without using any additional library.
- For Go (golang) examples, see go-res package
- For C# (NETCore) examples, see RES Service for .NET
| Example | Description |
|---|---|
| Hello World | Simple service serving a static message. |
| Edit Text | Text field that can be edited by multiple clients concurrently. |
| Book Collection | List of book titles & authors that can be edited by many. |
| JWT Authentication | Showing how JWT tokens can be used for authentication. |
| Password Authentication | Showing authentication with user and password credentials. |
| Client Session | Creating client sessions that survive reloads and reconnects. |
Note
All examples are complete with both service and client.
Protocol Specification
For more in depth information on the protocol:
- RES protocol - Introduction and general terminology
- RES-Service protocol - How to write services
- RES-Client protocol - How to write client libraries, if ResClient doesn't fit your needs
Usage
resgate [options]
Server options
| Option | Description | Default value |
|---|---|---|
-n, --nats <url> |
NATS Server URL | nats://127.0.0.1:4222 |
-i, --addr <host> |
Bind to HOST address | 0.0.0.0 |
-p, --port <port> |
HTTP port for client connections | 8080 |
-w, --wspath <path> |
WebSocket path for clients | / |
-a, --apipath <path> |
Web resource path for clients | /api/ |
-r, --reqtimeout <seconds> |
Timeout duration for NATS requests | 3000 |
-u, --headauth <method> |
Resource method for header authentication | |
-t, --wsheadauth <method> |
Resource method for WebSocket header authentication | |
-m, --metricsport <port> |
HTTP port for OpenMetrics connections | 0 (disabled) |
--apiencoding <type> |
Encoding for web resources: json, jsonflat | json |
--putmethod <methodName> |
Call method name mapped to HTTP PUT requests | |
--deletemethod <methodName> |
Call method name mapped to HTTP DELETE requests | |
--patchmethod <methodName> |
Call method name mapped to HTTP PATCH requests | |
--wscompression |
Enable WebSocket per message compression | |
--resetthrottle <limit> |
Limit on parallel requests sent on a system reset | 0 (no limit) |
--referencethrottle <limit> |
Limit on parallel requests sent following references | 0 (no limit) |
-c, --config <file> |
Configuration file in JSON format |
Security options
| Option | Description | Default value |
|---|---|---|
--tls |
Enable TLS for HTTP | false |
--tlscert <file> |
HTTP server certificate file | |
--tlskey <file> |
Private key for HTTP server certificate | |
--creds <file> |
NATS User Credentials file | |
--natscert <file> |
NATS Client certificate file | |
--natskey <file> |
NATS Client certificate key file | |
--natsrootca <file> |
NATS Root CA file(s) | |
--alloworigin <origin> |
Allowed origin(s): *, or ://\[:\] | * |
Logging options
| Option | Description |
|---|---|
-D, --debug |
Enable debugging output |
-V, --trace |
Enable trace logging |
-DV |
Debug and trace |
Common options
| Option | Description |
|---|---|
-h, --help |
Show usage message |
-v, --version |
Show version |
Configuration
Configuration is a JSON encoded file. If no config file is found at the given path, a new file will be created with default values as follows.
Properties
{
// URL to the NATS server.
"natsUrl": "nats://127.0.0.1:4222",
// Bind to HOST IPv4 or IPv6 address.
// Empty string ("") means all IPv4 and IPv6 addresses.
// Invalid or missing IP address defaults to 0.0.0.0.
"addr": "0.0.0.0",
// Port for the http server to listen on.
// If the port value is missing or 0, standard http(s) port is used.
"port": 8080,
// Metrics port for the OpenMetrics http server to listen on.
// If the port value is missing or 0, metrics are disabled.
// Must be different from the configured api port.
// Metrics are available at the path: /metrics
"metricsPort": 0,
// Path for accessing the RES API WebSocket.
"wsPath": "/",
// Path prefix for accessing web resources.
"apiPath": "/api",
// Timeout in milliseconds for NATS requests.
"requestTimeout": 3000,
// Size of message buffer for incoming NATS requests.
"bufferSize": 8192,
// Header authentication resource method for web resources.
// Prior to accessing the resource, this resource metho