Remote Modules

Defining API endpoints as remote modules and calling them with fetch/invoke.

Remote modules describe your back-end API in one place; the remote manager turns them into fetch calls with token handling included.

Defining modules

Pass modules in the remote option. Every app needs at least remote: {} — without the option at all, init() throws.

export const myApp = new Application( {
	remote: {
		modules: {
			user: {
				read:     { url: "/api/users/:userID" },
				readAll:  { url: "/api/users" },
				create:   { url: "/api/users" },
				update:   { url: "/api/users/:userID" },
				destroy:  { url: "/api/users/:userID" },
				search:   { url: "/api/users/search", params: { method: "POST" } }
			}
		},
		useTokens: true,                 // default: send the session token with secure calls
		tokenType: "X-Token",            // or "access_token" (Authorization: Bearer)
		credentials: "same-origin"       // "include" for SAML / cross-origin cookie SSO
	}
} );

Method shapes:

  • Object form { url, params } — the framework performs the fetch. Standard action names map to HTTP verbs: create → POST, read/readAll → GET, update → PUT, destroy → DELETE. :param segments in the URL are replaced from the params object. Custom names use params.method (default GET) and params.headers.
  • Function form — receives the params object and returns a fetch Response; use it when you need full control.

Calling methods

// invoke takes "module.action" strings
const response = await myApp.remote.invoke( "user.read", { userID: 7 } );
const user = await response.json();

const created = await myApp.remote.invoke( "user.create", { name: "Rob" } );

// custom methods work the same way
const found = await myApp.remote.invoke( "user.search", { q: "rob" } );

When called through a Service, entity conversion, caching and deduplication happen automatically — prefer services for anything entity-shaped.

Raw fetch

myApp.remote.fetch( uri, params, secure ) is the escape hatch:

const response = await myApp.remote.fetch(
	"/api/widgets/42",
	{ method: "GET" },
	true          // secure = attach the session token
);

With useTokens: true, secure calls send the token — as the X-Token header (default) or as Authorization: Bearer <token> when tokenType is "access_token". The token is set at login from the corresponding response header and kept in sessionStorage, so it survives page reloads.

Authentication endpoints

The loginURL, logoutURL and refreshURL settings define the three built-in auth endpoints; see Authentication.

Set credentials: "include" so every fetch sends cookies cross-origin (and the server must answer the CORS preflight with the right Access-Control-Allow-Credentials). This is how altseven apps integrate with a SAML identity provider: the session lives in cookies, not in the token header.