Members

abstract, static DESC

api.js, line 164

A human-readable description of what this API does. It is only used when automatically generating the Swagger documentation for the API. When used with the Swagger docs, newlines will be replaced with a single space character. May use Markdown formatting.

static NAME

api.js, line 64

The API's human-readable name. By default, this is computed by de-camel-casing the class name.

abstract, static PATH

api.js, line 140

The HTTP path suffix used to request this API. For consistency, PATHs should use lower camel-case as in the example mentioned; they should not contain underscores.

BODY

api.js, line 203

The Todea schema describing the request body this API handles. Note that GET requests should not have request bodies. Use HTTP POST requests if request data size is too big to fit in the query string.

CORS_HEADERS

api.js, line 271

The header(s) which are allowed in CORS requests.

CORS_ORIGIN

api.js, line 251

The hostname from which this API can be called in a browser. By default this API cannot be called from a browser due to CORS policy (combined with the fact that no web application runs on our API subdomain).

ENABLE_PAGINATION

api.js, line 123

Whether this API should have pagination parameters attached automatically. When true, the API will have 'nextToken' field attached to the QS and RESPONSE, and 'amount' field attached to QS automatically. To enable pagination, RESPONSE must contain exactly one key with an array schema.

ERRORS

api.js, line 224

Errors that may be returned from the API. Errors are subclasses of RequestError.

HEADERS

api.js, line 186

The Todea schema describing the HTTP headers this API handles, if any.

LOG_REQUEST_BODY_ON_ERROR

api.js, line 230

Whether to log request body to Sentry when error. For API with sensitive user data, this shouldn't set to true.

METHOD

api.js, line 130

The HTTP method used to request this API (e.g., GET, POST).

PATH_PARAMS

api.js, line 191

The Todea schema describing the path params this API handles, if any.

QS

api.js, line 196

The Todea schema describing the query string this API handles, if any.

RESPONSE

api.js, line 218

The schema describes the response body. This is used to verify that the implementation produces a correctly shaped output. It also speeds up JSON output serialization by 10-20%. This can return one of two things: 1) {@see ResponseSchema} - responses with HTTP 200 status codes will be validated against this schema. Non-200 responses can be anything. This is the typical return value. 2) A subclass of {@see RequestDone}. The default is to not allow any output on HTTP 200 responses.

SDK_GROUP

api.js, line 115

Defines which SDK this API should be part of. Can be 'user', 'admin', 'service' or null.

TAG

api.js, line 180

Tag used to group APIs in the generated Swagger documentation. Set to null to exclude it from the generated Swagger documentation.

Methods

static __makeParamsWithDefaultValuesOptional(schema)

api.js, line 497

Removes the required marker from any top-level properties which have a default value.

Parameters:

Name	Type	Description
schema	TodeaSchema	a Todea schema

async, static _callAndHandleRequestDone(reply, func)

api.js, line 314

Runs func and catches and handles RequestDone, if it is thrown.

Parameters:

Name	Type	Description
reply	fastify-reply	the reply object
func	function	the function to run

Returns:

- the response data

protected, static _getBody()

api.js, line 537

Returns the body schema.

static _getEmptySuccessResponse()

api.js, line 660

Return a default empty response matching the type specified in success response schema.

protected, static _getErrors()

api.js, line 630

Return all errors an API may return. Common base classes may use this method to add common errors, so users of the common base class can specify ERRORS without special considerations.

protected, static _getHeaders()

api.js, line 519

Returns the headers schema.

protected, static _getResponse()

api.js, line 545

Return a response wrapped in a subclass of RequestDone.

static _getResponseSchemas()

api.js, line 642

Return a mapping from status code to Todea schemas.

async, static _handleError(err, reply)

api.js, line 680

Handle an error thrown from API. Raise exceptions when errors that were not explicitly listed in ERRORS is thrown in test environment. Re-throw exceptions as 400 and 500 errors in production environment.

Parameters:

Name	Type	Description
err	Error	A subclass of Error.
reply	Object	Reply object

static getCORSOrigin()

api.js, line 257

Returns the CORS origin to use. On localhost, a non-wildcard CORS_ORIGIN is returned as the localhost web app domain instead.

static getDescMarkdownString()

api.js, line 170

Returns DESC as a string ready for output as Markdown.

static getFullPath(service)

api.js, line 150

Returns the full HTTP path to this API.

Parameters:

Name	Type	Description
service	String	The service this API belongs to.

package, static registerAPI(app, service)

api.js, line 456

Registers this API with the fastify app. This is called by internal implementation details in make-app.js. In rare occasions, subclasses may override this functionality to register the API with special middleware or other custom options. If the API allows CORS requests, then an OPTIONS API with the same path will also be registered to support browsers' CORS preflight requests.

Parameters:

Name	Type	Description
app	*	The fastify app to service this API from.
service	String	The service this API belongs to.

__setCORSHeaders(origin, headers)

api.js, line 281

Set headers to allow this API to be used in a browser from another origin.

Parameters:

Name	Type	Description
origin	string	the hostname from which this API can be called via CORS. On localhost, the origin is ignored and localhost is used instead.
headers	Array.<string>	an optional list of headers to allow when this API is requested via CORS

async _callAndHandleRequestDone(func, …args)

api.js, line 303

Runs func(...args) and catches and handles RequestDone, if it is thrown.

Parameters:

Name	Type	Attributes	Description
func	function		the function to run
args	any	<repeatable>	the arguments to call func with

Returns:

- the response data

async, protected _computeResponse() → {Object|String}

api.js, line 293

Calls computeResponse() inside _callAndHandleRequestDone().

Returns:

Object | String - the HTTP response body

addHeadersToForward(headers)

api.js, line 384

Adds (overwrites) headers with any header values from this request that should be forwarded.

Parameters:

Name	Type	Description
headers	Object	HTTP headers

async, abstract computeResponse(req) → {Object|String}

api.js, line 340

The API logic. This method is called after all inputs are validated according to the schemas specified by the API definition.

Parameters:

Name	Type	Description
req	Request	the fastify request object being handled

Returns:

Object | String - optional JSON-able object or string to send back as the HTTP response body

redirectToWebApp(qparamsopt, serviceopt, versionopt, cookieValuesopt)

api.js, line 408

Redirects to the URL hosting the specified web application.

Parameters:

Name	Type	Attributes	Description
qparams	Object	<optional>	the query string parameters to launch with
service	String	<optional>	the service the web application belongs to
version	String	<optional>	the version of the web application to launch; can be overridden by query parameter "version" but otherwise defaults to the version of the service which served the web app
cookieValues	Object	<optional>	values to pass in a cookie (good for sensitive values which should not be passed in in qparams, and for values which need to included with Todea HTTP requests the app makes)