sitemap.xml llms.txt
Skip to main content

Routers

Version type​

The Version (number or undefined): version number

Server type​

The Server (string or undefined): server address

UseProjectProxy type​

The UseProjectProxy (boolean or undefined) indicates whether a project proxy is used.

AccountShortName type​

The AccountShortName (string or undefined): short name for an account

ProjectShortName type​

The ProjectShortName (string or undefined): short name for a project

Authorization type​

The Authorization (string or undefined): authorization token

QueryObject type​

The QueryObject type is a record of key-value pairs where the keys are strings and the values are of unknown type.

SearchParams type​

The SearchParams type defines possible search parameters, which can be:

  • A string
  • A two-dimensional string array
  • A URLSearchParams object
  • A QueryObject

RoutingOptions interface​

The RoutingOptions interface defines options for routing requests.

Properties​

  • authorization? (Authorization): (Optional) Authorization token.
  • server? (Server): (Optional) Server address.
  • useProjectProxy? (UseProjectProxy): (Optional) Indicates if a project proxy should be used.
  • accountShortName? (AccountShortName): (Optional) Short name of the account.
  • projectShortName? (ProjectShortName): (Optional) Short name of the project.
  • query? (SearchParams): (Optional) Query parameters for the request.
  • headers? (Record<string, string>): (Optional) Headers to be included in the request.
  • body? (unknown): (Optional) The request body.
  • includeAuthorization? (boolean): (Optional) Determines whether authorization should be included.
  • inert? (boolean | ((fault: Fault) => boolean)): (Optional) When true, indicates an operation that is not state-changing.
  • paginated? (boolean): (Optional) Set to true when making a request to a paginated endpoint directly through the Router. Not needed for requests made through adapter methods.
  • parsePage? ((values: any[]) => any[]): (Optional) A function to parse paginated response values.
tip

Adapter methods handle paginated requests for you. It is recommended to use adapter methods rather than make requests through the Router class whenever possible.

warning

The parsePage property uses any for flexibility but may require careful handling to ensure type safety.

Page interface​

Page<Item> describes a paginated response returned by the adapter functions when paginated: true is passed via RoutingOptions.

Properties​

  • firstResult (number): The index of the first item in this page.
  • maxResults (number): The maximum number of items requested per page.
  • resultSize (number): The number of items actually returned in this page.
  • totalResults (number): The total number of items across all pages.
  • values (Item[]): The items in this page.
  • prev (() => Promise<Item[]>): Fetches the previous page of results and updates this Page object in place.
  • next (() => Promise<Item[]>): Fetches the next page of results and updates this Page object in place.
  • all ((first?: number, allValues?: Item[]) => Promise<Item[]>): Fetches every remaining page and returns all items combined.
tip

Use next(), prev(), or all() on the result to page through it.

Router class​

Used internally by every adapter to make network calls. Adapter methods handle constructing and configuring a Router for you.

Important

The recommended practice is to use the adapter methods. However, you can also use a Router instance to make calls to the API.

Constructor​

Function signature
new Router()

Creates a new Router instance. The version, server, account, project, and authorization are set automatically to the values in your project. You can override them either with the properties or the chaining methods.

Properties​

Each of the following is both a getter and a setter. Setting one of these directly overrides what the Router would otherwise fall back to.

  • version (Version): The version of the Epicenter APIs being invoked.
  • server (Server): The root path used for the call — essentially protocol + hostname (e.g. https://forio.com).
  • useProjectProxy (UseProjectProxy): If true, requests are routed to the project proxy server. In that case, all request paths are prefixed with proxy/${accountShortName}/${projectShortName}/.
  • accountShortName (AccountShortName): Name of the account.
  • projectShortName (ProjectShortName): Name of the project.
  • authorization (Authorization): Auth header value. Looks like Bearer TOKEN or Basic TOKEN.
  • searchParams (URLSearchParams): The search parameters to use when making a network request. Always returns an instance of URLSearchParams. Setting it accepts a string, a two-dimensional string array, a plain object (including one with arrayed values), or a URLSearchParams instance. See the example below.
searchParams usage
const router = new Router();
router.searchParams = '?foo=123';
console.log(router.searchParams);                            // always returns an instance object: URLSearchParams {}
console.log(router.searchParams.toString());                 // logs 'foo=123'

router.searchParams = 'foo=123';                              // can omit the question mark
console.log(router.searchParams.toString());                 // logs 'foo=123'

router.searchParams = [['foo', '123'], ['bar', '456']];       // can accept arrays
console.log(router.searchParams.toString());                 // logs 'foo=123&bar=456'

router.searchParams = { foo: '123', bar: '456' };             // can accept objects
console.log(router.searchParams.toString());                 // logs 'foo=123&bar=456'

router.searchParams = { foo: '123', bar: ['4', '5', '6'] };   // can accept objects with arrayed values
console.log(router.searchParams.toString());                 // logs 'foo=123&bar=4&bar=5&bar=6'

router.searchParams = new URLSearchParams('foo=123');         // can accept instances of URLSearchParams
console.log(router.searchParams.toString());                 // logs 'foo=123'

Chaining methods​

Each of these methods sets the corresponding property and returns the Router instance, so calls can be chained. Each does nothing if invoked with no input (or undefined), leaving the existing value in place.

  • withVersion(version?: Version): Router — Sets version.
  • withServer(server?: Server): Router — Sets server.
  • withProjectProxy(useProjectProxy?: UseProjectProxy): Router — Sets useProjectProxy.
  • withAccountShortName(accountShortName?: AccountShortName): Router — Sets accountShortName.
  • withProjectShortName(projectShortName?: ProjectShortName): Router — Sets projectShortName.
  • withAuthorization(authorization?: Authorization): Router — Sets authorization.
  • withSearchParams(searchParams?: SearchParams): Router — Sets searchParams; accepts the same value types as the searchParams setter.
Chaining example
import { Router } from 'epicenter-libs';

const router = new Router()
    .withAccountShortName('acme')
    .withProjectShortName('simulations')
    .withSearchParams({ foo: '123' });

getURL() function​

Creates the URL that would be used for a network request, without making the request. Prioritizes any overrides provided, then falls back to values set on the Router instance, then to values set in your project.

Function signature
getURL(
    uriComponent: string,
    overrides: {
        server?: string;
        useProjectProxy?: boolean;
        accountShortName?: string;
        projectShortName?: string;
        version?: number;
        query?: SearchParams;
    } = {},
): URL

Parameters​

  • uriComponent (string): The URI component (path) used to generate the URL, appended after the account/project path
  • overrides (optional): Overrides for generating the URL
    • server? (string): Override for the root URL string — composed of the protocol and hostname (e.g. https://forio.com)
    • useProjectProxy? (boolean): Override for routing requests to the project proxy server
    • accountShortName? (string): Override for the account short name
    • projectShortName? (string): Override for the project short name
    • version? (number): Override for the API version
    • query? (SearchParams): Override for the URL's search query

Return value​

A URL object.

Network methods​

These methods issue the actual network request and return a Promise resolving to a Result object. Every RoutingOptions field can be passed as the second argument to override what the Router instance would otherwise fall back to. includeAuthorization defaults to true for every method.

Function signatures
async get(uriComponent: string, options: RoutingOptions = {}): Promise<Result>
async delete(uriComponent: string, options: RoutingOptions = {}): Promise<Result>
async patch(uriComponent: string, options: RoutingOptions = {}): Promise<Result>
async post(uriComponent: string, options: RoutingOptions = {}): Promise<Result>
async put(uriComponent: string, options: RoutingOptions = {}): Promise<Result>

Parameters​

  • uriComponent (string): The URI component (path) for the request
  • options (RoutingOptions, optional): Network call options. body is only meaningful for patch, post, and put.

Return value​

A Promise resolving to a Result object. If options.paginated is true, result.body is a Page object instead of a plain array.

warning

If the composed request URL would exceed 2048 characters, the request throws an EpicenterError instead of being sent.

Usage example​

import { Router } from 'epicenter-libs';

const router = new Router();
const result = await router.get('/group', { query: { includeExpired: true } });
console.log(result.body);