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
Run npm start
. The server listens on port 7888 by default.
Semserver runs as-is on now.sh. Run now
in the folder to deploy it.
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.
URL parameter | Description |
---|---|
service |
The name of the service you're registering |
version |
The version of the service you're registering. Must be a valid Semver version. |
Post parameter | Description |
---|---|
endpoint |
The HTTP endpoint for this version of the service |
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
.
Status code | Description |
---|---|
400 |
The version is not a valid semver string |
409 |
The version already exists for this service |
Returns an object listing the registered versions of the service and their endpoints.
URL parameter | Description |
---|---|
service |
The name of the service you're requesting |
version |
The version of the service you're requesting. Must be a valid Semver version or version range. |
path |
The path you're requesting of the service |
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.
Status code | Description |
---|---|
307 |
Temporary redirect to the highest service version that matches the version range |
308 |
Permanent redirect to the exact version requested |
400 |
The version is not a valid semver range string |
404 |
The service doesn't exist in the registry at all |
501 |
The service has no versions that match the range or exact version you wanted |
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.
We also provide a client library, which is a thin wrapper around got
.
const semserver = require('semserver');
const registry = semserver('https://semserver.example.com');
const service = registry('my-service', '^1.0.0');
service('/thing/1').then(...);
ISC. © Kara Brightwell