HTTP API v1

All API access is over HTTPS and accessed from https://api.jamsocket.com/v1/.

Authentication

Jamsocket uses access tokens for authentication with its API. For those endpoints which require authentication, the Jamsocket API uses a Bearer Authorization header like the following, where <token> is an access token you’ve generated on the Jamsocket Settings page:

Authorization: Bearer <token>

Check authentication credentials

GET /auth

Returns {"status":"ok"} if auth headers are valid. Otherwise returns a 401 status code.

Services

Create service

POST /user/{account}/service

Request body:

{ name: string }

Returns { "status": "ok" } if successful.

Get a list of services

GET /user/{account}/services

Returns a list of the user’s services.

Example response

{ "services": ["hello-world", "my-service"] }

Backends

Spawn a backend

POST /user/{account}/service/{service}/spawn

Request body:

{
  tag?: string,
  grace_period_seconds?: number,
  lock?: string,
  env?: {
    [env_var: string]: string
  }
}

Note: Environment variables passed in env may not be one of the reserved env vars PORT, SESSION_BACKEND_ID, SESSION_BACKEND_KEY, SESSION_BACKEND_FENCING_TOKEN, or JAMSOCKET_SERVICE. Learn more about the environment variables we pass into all backend containers here.

Returns the following values:

• name - the backend’s name or ID
• url - the connection url used to route requests to the spawned backend
• ready_url - a browser-friendly URL that displays a loading page and which redirects to the backend’s url once the backend has a Ready status
• status_url - a Jamsocket API endpoint that returns the backend’s most recent status (see the /backend/{backend_name}/status endpoint)
• status - the current status of the backend returned from the spawn request, is usually Loading but may be another status if the backend returned was already running due to spawning with a key (aka lock)
• spawned - is true if the spawn request resulted in a newly-spawned backend, may be false if an existing backend is currently holding the given key (aka lock) (read more about spawning with keys)

Example response

{
  "url": "https://8nyg2.p.jamsocket.net/eqYLfYmVbdIwSukbIxiFJNAjKz8KJLECmfYMQfqSgKs/",
  "name": "8nyg2",
  "ready_url": "https://api.jamsocket.com/ready/8nyg2/eqYLfYmVbdIwSukbIxiFJNAjKz8KJLECmfYMQfqSgKs/",
  "status_url": "https://api.jamsocket.com/backend/8nyg2/status",
  "spawned": true,
  "status": "Loading"
}

Fetch a backend holding a given key

POST /user/{account}/service/{service}/fetch

Request body:

{
  lock: string
}

This endpoint returns the backend holding a given key (previously known as “lock”). If no backend is holding the key, it returns a 404. The endpoint is also designed to match the above spawn endpoint as closely as possible, so its response is exactly the same. You can learn more about spawning with keys in our keys documentation.

Returns the following values:

• name - the name (i.e. ID) of the running backend holding the given key (aka lock)
• url - the connection url used to route requests to the spawned backend
• ready_url - a browser-friendly URL that displays a loading page and which redirects to the backend’s url once the backend has a Ready status
• status_url - a Jamsocket API endpoint that returns the backend’s most recent status (see the /backend/{backend_name}/status endpoint)
• status - the current status of the backend returned from the spawn request
• spawned - is always false - indicates whether the backend was spawned as a result of the request (this field exists to match the spawn endpoint’s response)

Example response

{
  "url": "https://8nyg2.p.jamsocket.net/eqYLfYmVbdIwSukbIxiFJNAjKz8KJLECmfYMQfqSgKs/",
  "name": "8nyg2",
  "ready_url": "https://api.jamsocket.com/ready/8nyg2/eqYLfYmVbdIwSukbIxiFJNAjKz8KJLECmfYMQfqSgKs/",
  "status_url": "https://api.jamsocket.com/backend/8nyg2/status",
  "spawned": false,
  "status": "Starting"
}

Get a backend’s logs

GET /backend/{backend_name}/logs

Streams application logs from the given backend.

Example response

data: > node-hello-world@0.0.1 start
data: > node src/server.js
data:
data: Example app listening on port 8080

Get a backend’s status stream

GET /backend/{backend_name}/status/stream

Response is a stream where each line looks like:

data:{"state":"Ready","time":"2022-04-13T18:00:10.985294Z"}

Backend statuses

• Loading - the backend has been created, and the image is being fetched

• Starting - the image has been fetched and is running but is not yet listening on port 8080

• Ready - the backend is listening on port 8080

• Swept - the backend was terminated by Jamsocket because all connections were closed for the grace period

• Exited - the backend exited on its own with a zero status

• ErrorLoading - a failure occurred while loading the image

• ErrorStarting - a failure occurred while starting the backend

• TimedOutBeforeReady - a timeout occurred while waiting for the backend to become Ready

• Failed - the backend exited on its own with a non-zero status

• Terminated - the backend was terminated externally

• Lost - the backend stopped running but its status wasn’t updated due to a Jamsocket error

Get a backend’s current status

GET /backend/{backend_name}/status

Same as /backend/{backend_name}/status/stream except returns only the most recent status.

Example response

{"state":"Ready","time":"2022-04-13T18:00:21.719786Z"}

Backend ready page

GET /backend/{backend_name}/ready

Serves a webpage that shows a loading screen for newly-spawned backends. The page listens for the backend’s Ready event, after which it does a client-side redirect to the backend’s url.

Terminate a backend

POST /backend/{backend_name}/terminate

Terminate a backend. In most cases, you do not need to call this; backends will be terminated automatically after a period with no open connections (see grace_period_seconds in the spawn request.)

Returns {"status":"ok"} if termination request was successfully sent to backend.

CORS

Endpoints that support CORS currently allow all origins to read the response.

Backend Containers

• Backends must listen on the port provided by the PORT env var (8080) in order for Jamsocket to detect when the backend is ready and for Jamsocket to proxy outside requests to the backend.
• Currently Jamsocket will only allow HTTP requests and Sockets connections to be proxied to the backend.
• All backends will have the following reserved env vars passed to them. Env vars with these names passed by the user when spawning will be overridden by the platform-provided values.
  • PORT (always 8080) - this is the port that session backend requests will be proxied to. You shoud run a server in your session backend on this port.
  • JAMSOCKET_SERVICE - this is your Jamsocket service’s name.
  • SESSION_BACKEND_ID - a short, unique alphanumeric ID for your backend. This appears in the dashboard and can be used with the Jamsocket CLI. (Note: this is sometimes called the backend’s “name”.)
  • SESSION_BACKEND_KEY - this is the key (previously known as “lock”) your backend was spawned with. (Learn more about keys in our keys explainer.)
  • SESSION_BACKEND_FENCING_TOKEN - this is a number that increases every time the key is assigned. It can be used as a fencing token. Most applications will not need to use this.

Working directly with the Jamsocket Container Registry

It is possible to push to and pull from the Jamsocket Container Registry directly. The registry is hosted at registry.jamsocket.com, and images are expected to follow the naming scheme [ACCOUNT]/[SERVICE]. For example, taylor/hello-world.

When logging into the container registry with docker login, use the account name as the username and an access token as the password. You can generate an access token at app.jamsocket.com/settings.