Server API and Reference

Related documents

• Aeronautical Server API and reference

Table of contents

• Introduction
  • Origin server
• server fetch methods
  • fetch()
  • get()
  • post()
  • stdOp()
• server API methods
  • archiveTr()
  • deleteUserData()
  • getBackups()
  • getSavedInput()
  • getTr()
  • mailSaveIds()
  • sendEmail()
  • setSavedInput()
  • setTr()
  • startSession()
• server properties
  • baseUrl
  • id
  • isEnabled
  • opSuffix
  • stdHeaders
  • timeout

Introduction

The server object that provides access to the following server-based functions:

• Log the start of a user session.
• Save and backup user input, retrieve saved user input, retrieve backup user input, and delete user input from the server.
• Find passwords associated with a user.
• Email content to a user.
• Submit, load, and archive trouble reports.

The server object also has generic methods to aid in fetching server results and methods to invoke server-based functions. See server fetch methods and server API methods.

Origin server

The server.baseUrl property contains the URL for the root of the server serving the API. By default, this is set to the origin server. However, the app can be invoked in a variety of environments: from an Internet server, from a local HTTP server, and from within a Cordova native app. In each case, the app.js startup file, can decide where the server resides by setting server.baseUrl. For example, POH Performance apps invoked in a Cordova native app set server.baseUrl to https://pohperformance.com/${appId}.

server fetch methods

The fetch methods in the server object provide a simplified interface to the fetch() function.

• server.fetch()
  Provides an optimized interface to the fetch() function optimized for passing requests with arguments and providing a timeout capability.
• server.get()
  Calls server.fetch() specifying the GET method.
• server.post()
  Calls server.fetch() specifying the POST method.
• server.stdOp()
  Calls server.fetch() specifying the POST method and added arguments shared by all standard MVCS API functions.

fetch()

Syntax

server.fetch(url, method)
server.fetch(url, method, args)
server.fetch(url, method, args, options)
server.fetch(url, method, args, options, timeout)

Fetches the url using the method ('GET' or 'POST'), passing the arguments in the args object, and returns a Promise that resolves to the fetched Response if the Response status is OK (HTTP status code 200). If the Response is not OK, then the Response is passed as the rejection of the Promise.

If timeout is provided and non-zero, the request will time out in the specified number of milliseconds. If timeout is omitted, then it defaults to the value specified by the server.timeout property, which is set to 20 seconds initially. If the timeout expires, the Promise is rejected with a Response code of 524 (Connection Timed Out).

Parameters

• url
  The URL for the request.
• method
  Specified which request method to use:
  • 'GET': Use the GET method.
  • 'POST': Use the POST method.
• args (optional)
  An Object specifying the arguments to pass in the request. If not provided this defaults to an empty Object.
• options (optional)
  An Object specifying the options to pass to fetch(). If not provided this defaults to an empty Object. POST requests will fill options.body with the arguments.
• timeout (optional)
  A number of milliseconds to wait for a response before aborting the request and rejecting the Promise with a Response code of 524. If timeout is 0, then the fetch will wait for a response without a timeout. If timeout is omitted, then it defaults to the value in server.timeout, which is set to 20 seconds initially.

Return value

A Promise that resolves with the returned Response if the status is OK. Otherwise, the promise is rejected with the returned or timeout Response.

get()

Syntax

server.get(url)
server.get(url, args)
server.get(url, args, options)
server.get(url, args, options, timeout)

Fetches the url using the GET method, passing the arguments in the args object, and returns a Promise that resolves to the fetched Response if the Response status is OK (HTTP status code 200). If the Response is not OK, then the Response is passed as the rejection of the Promise.

If timeout is provided and non-zero, the request will time out in the specified number of milliseconds. If timeout is omitted, then it defaults to the value specified by the server.timeout property, which is set to 20 seconds initially. If the timeout expires, the Promise is rejected with a Response code of 524 (Connection Timed Out).

Parameters

• url
  The URL for the request.
• args (optional)
  An Object specifying the arguments to pass in the request. If not provided this defaults to an empty Object.
• options (optional)
  An Object specifying the options to pass to fetch(). If not provided this defaults to an empty Object. POST requests will fill options.body with the arguments.
• timeout (optional)
  A number of milliseconds to wait for a response before aborting the request and rejecting the Promise with a Response code of 524. If timeout is 0, then the fetch will wait for a response without a timeout. If timeout is omitted, then it defaults to the value in server.timeout, which is set to 20 seconds initially.

Return value

A Promise that resolves with the returned Response if the status is OK. Otherwise, the promise is rejected with the fetch Response or timeout Response.

post()

Syntax

server.post(url)
server.post(url, args)
server.post(url, args, options)
server.post(url, args, options, timeout)

Fetches the url using the POST method, passing the arguments in the args object, and returns a Promise that resolves to the fetched Response if the Response status is OK (HTTP status code 200). If the Response is not OK, then the Response is passed as the rejection of the Promise.

If timeout is provided and non-zero, the request will time out in the specified number of milliseconds. If timeout is omitted, then it defaults to the value specified by the server.timeout property, which is set to 20 seconds initially. If the timeout expires, the Promise is rejected with a Response code of 524 (Connection Timed Out).

Parameters

• url
  The URL for the request.
• args (optional)
  An Object specifying the arguments to pass in the request. If not provided this defaults to an empty Object.
• options (optional)
  An Object specifying the options to pass to fetch(). If not provided this defaults to an empty Object. POST requests will fill options.body with the arguments.
• timeout (optional)
  A number of milliseconds to wait for a response before aborting the request and rejecting the Promise with a Response code of 524. If timeout is 0, then the fetch will wait for a response without a timeout. If timeout is omitted, then it defaults to the value in server.timeout, which is set to 20 seconds initially.

Return value

A Promise that resolves with the returned Response if the status is OK. Otherwise, the promise is rejected with the fetch Response or timeout Response.

stdOp()

Syntax

server.stdOp(op, opVersion)
server.stdOp(op, opVersion, args)
server.stdOp(op, opVersion, args, options)
server.stdOp(op, opVersion, args, options, timeout)

Fetches the server op URL using the POST method, passing the arguments in the args object and standard arguments. The URL is constructed as /${ctl.appId}/${op}${server.opSuffix}. The standard arguments are:

• appVersion
  The version of the app taken from ctl.appVersion.
• opVersion
  The operation version from the opVersion argument.
• id
  The user id or GUID copied from server.id. In recent app versions (post 5.0.0 for POH Performance apps) server.id is set to a JSON string containing an object with email, password, and guid elements.

In addition, server.stdOp() sets HTTP request headers to disable caching.

server.stdOp() returns a Promise that resolves to the fetched Response if the Response status is OK (HTTP status code 200). If the Response is not OK, then the Response is passed as the rejection of the Promise.

If timeout is provided and non-zero, the request will time out in the specified number of milliseconds. If timeout is omitted, then it defaults to the value specified by the server.timeout property, which is set to 20 seconds initially. If the timeout expires, the Promise is rejected with a Response code of 524 (Connection Timed Out).

Parameters

• op
  The operation name string (e.g. 'startSession', 'getSavedInput'). Used to construct the request URL as /${ctl.appId}/${op}${server.opSuffix}.
• opVersion
  The operation version string (e.g. '1', '2'). Passed to the server as part of the request body.
• args (optional)
  An Object specifying the arguments to pass in the request. If not provided this defaults to an empty Object.
• options (optional)
  An Object specifying the options to pass to fetch(). If not provided this defaults to an empty Object.
• timeout (optional)
  A number of milliseconds to wait for a response before aborting the request and rejecting the Promise with a Response code of 524. If timeout is 0, then the fetch will wait for a response without a timeout. If timeout is omitted, then it defaults to the value in server.timeout, which is set to 20 seconds initially.

Return value

A Promise that resolves with the returned Response if the status is OK. Otherwise, the promise is rejected with the fetch Response or timeout Response.

server API methods

The server API methods are functions that invoke server API operations. All server API methods call the server.stdOp() method to pass the standard arguments, in addition to ant argument unique to the operation. They fall into the following categories:

• Normal operations.
  These operations are issued in the background during a normal session. They mark the start of a user session and save and restore user input.
  • server.getSavedInput()
  • server.setSavedInput()
  • server.startSession()
• Trouble Report operations.
  These operations are used by a user to submit a Trouble Report and by the webmaster to load and archive submitted Trouble Reports. Each Trouble Report is normal saved user input with an internal state variable, set_trData that has additional information, including the problem description and state variable values not normally included when saving.
  • server.archiveTr()
  • server.getTr()
  • server.setTr()
• Special operations.
  These operations are only invoked only by user request. The get backup data to restore, recover lost passwords, and send results back to the user.
  • server.getBackups()
  • server.mailSaveIds()
  • server.sendEmail()

archiveTr()

Syntax

server.archiveTr(trId)

Archive Trouble Report trId. The trId must be a valid Trouble Report ID created by the setTr() method. Once archived, the server will no longer consider it an outstanding Trouble Report and will not remind the Webmaster about it. Returns a Promise that either resolves to indicate success or rejects with a status code to indicate the failure.

server.archiveTr() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Parameters

• trId
  A Trouble Report ID.

Return value

A Promise that resolves with the returned Response if the status is OK. No data is returned in the Response. Otherwise, the Promise is rejected with the returned or timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 410 Gone: The TR file cannot be archived.
• 524 Connection Timed Out.

deleteUserData()

Syntax

server.deleteUserData()

Delete all the data associated with server.id. Returns a Promise that resolves with a Response. The Promise rejects if something goes wrong.

server.deleteUserData() calls server.stdOp() to pass the standard headers and arguments.

Return value

A Promise that resolves with the returned Response if the status is OK. If the Promise is rejected, the value is the returned Response, or a timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 524 Connection Timed Out.

getBackups()

Syntax

server.getBackups()

Get all the backups associated with server.id. Returns a Promise that resolves with a Response whose body contains a JSON array of all available backup data. Each backup consists of the data saved by server.setSavedInput(). The data contains a saveTime Date string that can be used to differentiate the backups. If no backups can be found, the array will be empty. The Promise rejects if something goes wrong.

server.getBackups() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains a JSON array of all available backup data. If the Promise is rejected, the value is the returned Response, or a timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 524 Connection Timed Out.

getSavedInput()

Syntax

server.getSavedInput()

Get the saved input associated with server.id. Returns a Promise that resolves with a Response whose body contains a JSON-encoded string of the saved input object. The Promise rejects if something goes wrong.

server.getSavedInput() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains a JSON-encoded string of the saved input object. If the Promise is rejected, the value is the returned Response, or a timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 410 Gone. The data file cannot be found.
• 524 Connection Timed Out.

getTr()

Syntax

server.getTr(trId)

Get the Trouble Report trId. The trId must be a valid Trouble Report ID created by the setTr() method. Returns a Promise that resolves with a Response whose body contains the JSON-encoded string of a saved input object. The Promise rejects if something goes wrong.

server.getTr() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Parameters

• trId
  A Trouble Report ID.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains the JSON-encoded string of a saved input object. Otherwise, the Promise is rejected with the returned or timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 410 Gone: The TR file cannot be found.
• 524 Connection Timed Out.

mailSaveIds()

Syntax

server.mailSaveIds()

Recover all passwords associated with the email address within server.id by emailing them to the email address. Returns a Promise that either resolves to indicate success or rejects with a status code to indicate the failure.

server.mailSaveIds() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains no data. Otherwise, the Promise is rejected with the returned or timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 410 Gone: No passwords associated with the id can be found..
• 524 Connection Timed Out.

sendEmail()

Syntax

server.sendEmail(to, subject, content)

Email the summarized app results. This is only allowed if there's an existing saved input file associate within server.id. Returns a Promise that either resolves to indicate success or rejects with a status code to indicate the failure.

server.sendEmail() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Parameters

• to
  An email address to send the results to.
• subject
  The email subject.
• content
  The email content.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains no data. Otherwise, the Promise is rejected with the returned or timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 403 Forbidden. A data file associated with the id cannot be found.
• 524 Connection Timed Out.

setSavedInput()

Syntax

server.setSavedInput(input)
server.setSavedInput(input, takeover)

Save the input on the server in a file associated with server.id. Returns a Promise that either resolves to indicate success or rejects with a status code to indicate the failure.

If takeover is omitted or false, then the request will be rejected if the guid value in the id does not match the guid field in the currently saved input. If takeover is true, then the input will overwrite any previously saved input.

server.setSavedInput() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains no data. Otherwise, the Promise is rejected with the returned or timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 409 Conflict: Error if the guid argument doesn't match the guid extracted from the
• existing data file.
• 410 Gone. The data file cannot be created or written.
• 524 Connection Timed Out.

setTr()

Syntax

server.setTr(data)

Create a Trouble Report that contains data, which is a JSON-encoded saved input string.
Get the Trouble Report trId. The trId must be a valid Trouble Report ID created by the setTr() method. Returns a Promise that resolves with a Response whose body contains a Trouble Report ID (trId) string. The Promise rejects if something goes wrong.

server.setTr() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Parameters

• data
  A JSON-encoded saved input string containing the Trouble Report Data.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains contains a Trouble Report ID (trId) string. Otherwise, the Promise is rejected with the returned or timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 410 Gone: The trouble report file cannot be written.
• 524 Connection Timed Out.

startSession()

Syntax

server.startSession(info)

Log the start of a user session. The contents of the info argument are attached to the log entry. Typically, this is a JSON-encoded object containing information about the issuing device. Returns a Promise that either resolves to indicate success or rejects with a status code to indicate the failure.

server.startSession() is typically called when the application starts, or the user restarts activity after a significant period of inactivity.

server.startSession() calls server.stdOp() to pass the standard headers and arguments in addition to the supplied arguments.

Parameters

• info
  A JSON-encoded object string containing information about the issuing device.

Return value

A Promise that resolves with the returned Response if the status is OK. The Response body contains no data. Otherwise, the Promise is rejected with the returned or timeout Response. The Response can contain the following status codes:

• 400 Bad Request: Missing required args.
• 524 Connection Timed Out.

server properties

baseUrl

The URL for the server root. This is set to the origin root by default. Set his property to something else if a different server is desired.

When in a native app (Cordova), most POH Performance apps will set this to: https://pohperformance.com/${appId}.

Value

A string to use as a base URL.

id

The value of the id argument passed to the fetch() method when using the stdOp() method.

This is typically set to a JSON-encoded object containing email, password, and guid properties.

Value

A string.

isEnabled

True if the server is enabled. This is set to true by default. Apps that don't use any remote service should set server.isEnabled to false on startup.

Value

A Boolean.

opSuffix

A suffix string appended to every operation name when constructing the URL in server.stdOp(). Defaults to ''. Set this property if you want a different default suffix for all operations.

Value

A string.

stdHeaders

The standard headers to include in the fetch() method options when using the stdOp() method.

This is initially set to:

{
	'Content-Type': 'application/x-www-form-urlencoded',
}

Value

An object whose properties are HTTP header names and values.

timeout

The default server operation timeout in milliseconds. This is initially set to 20 seconds.

Value

A number representing the server timeout in milliseconds.