semserver v1.0.0

Register a service version

> POST /my-service/1.0.0
>
> endpoint=http://my-service-adsfghjk.now.sh

and you can query it:

> GET /my-service/^1.0.0/thing/1

< HTTP/1.1 307 Temporary Redirect
< Location: http://my-service-adsfghjk.now.sh/thing/1

Register another version

> POST /my-service/1.1.0
>
> endpoint=http://my-service-zxcvbnm.now.sh

and you get the latest that satisfies the range:

> GET /my-service/^1.0.0/thing/1

< HTTP/1.1 307 Temporary Redirect
< Location: http://my-service-zxcvbnm.now.sh/thing/1

Server

Running

Run npm start. The server listens on port 7888 by default.

Deployment

Semserver runs as-is on now.sh. Run now in the folder to deploy it.

Authentication

If you want to prevent unauthorized users from registering services, start Semserver with an APIKEY environment variable, e.g. APIKEY=abcdef npm start, or deploy it with now -e APIKEY=abcdef. If the variable is set, requests to register a service will return a 401 Unauthorized unless you send an Authorization: Token [apikey] header.

Endpoints

POST /:service/:version

Registers a version of a service. Once registered, the version is immutable and will always point to this endpoint. Trying to register the same version again will return a 409 Conflict.

OPTIONS /:service

Returns an object listing the registered versions of the service and their endpoints.

* /:service/:versionOrRange/:path

Resolves a service version and issues a redirect to its endpoint.

If you provide an exact version (e.g. 1.2.3), you'll get a 308 Permanent Redirect. Service versions are immutable, so you can guarantee this version will always have this endpoint.

If instead you provide a semver range (e.g. 1.x.x, ^1.0.0), you'll get a 307 Temporary Redirect. Semserver resolves the highest version of the service that matches your version range and redirects to its endpoint.

Command line

So you can automatically register a service to a registry (e.g. on deploy), we provide a command line script. It's intended to be used as an npm script, and it takes your service name and version from package.json, as well as the registry host, which you should put in package.json as "semserver": {"host": "semserver.example.com"}. Finally, pass the endpoint you're registering as the single command line argument.

For example, if you're deploying to now.sh, you can use the now-build lifecycle script to register your service. Now provides the NOW_URL environment variable, so your package.json should look like:

{
	"name": "my-service",
	"version": "1.0.0",
	"scripts": {
		"now-start": "...",
		"now-build": "semserver $NOW_URL"
	},
	"dependencies": {
		"semserver": "^1.0.0"
	},
	"semserver": {
		"host": "semserver.example.com"
	}
}

If your semserver has an API key configured, use the environment variable SEMSERVER_KEY to tell the CLI about it.

Client library

We also provide a client library, which is a thin wrapper around got.

Usage

const semserver = require('semserver');
const registry = semserver('https://semserver.example.com');
const service = registry('my-service', '^1.0.0');

service('/thing/1').then(...);

Licence

ISC. © Matt Brennan