FunctionScript

An API gateway and framework for turning functions into web services

FunctionScript is a language and specification for turning JavaScript functions into typed HTTP APIs. It allows JavaScript (Node.js) functions to be seamlessly exported as HTTP APIs by defining what the HTTP interface will look like and how it behaves in the preceding comment block - including type-safety mechanisms.

FunctionScript arose out of a need to introduce developers with little programming experience, but familiarity with JavaScript, to full-stack API development and best practices around defining and connecting HTTP application interfaces. For this reason, the goals of the language are significantly different than TypeScript. FunctionScript is intended to provide an easy introduction to API development for those of any skill level, while maintaining professional power and flexibility.

FunctionScript is the primary specification underpinning the Autocode platform and its standard library of APIs.

Quick Example of a FunctionScript API

The following is a real-world excerpt of an API that can be used to query a Spreadsheet like a Database. The underlying implementation has been hidden, but the parameters for the API can be seen.

/**
* Select Rows from a Spreadsheet by querying it like a Database
* @param {string} spreadsheetId The id of the Spreadsheet.
* @param {string} range The A1 notation of the values to use as a table.
* @param {enum} bounds Specify the ending bounds of the table.
*   ["FIRST_EMPTY_ROW", "FIRST_EMPTY_ROW"]
*   ["FULL_RANGE", "FULL_RANGE"]
* @param {object} where A list of column values to filter by.
* @param {object} limit A limit representing the number of results to return
* @ {number} offset The offset of records to begin at
* @ {number} count The number of records to return, 0 will return all
* @returns {object} selectQueryResult
* @ {string} spreadsheetId
* @ {string} range
* @ {array} rows An array of objects corresponding to row values
*/
module.exports = async (
  spreadsheetId = null,
  range,
  bounds = 'FIRST_EMPTY_ROW',
  where = {},
  limit = {offset: 0, count: 0},
  context
) => {

  /* implementation-specific JavaScript */

  return {/* some data */};

};

It generates an API which accepts (and type checks against, following schemas):

• spreadsheetId A string
• range A string
• bounds An enum, can be either "FIRST_EMPTY_ROW" or "FULL_RANGE"
• where An object
• limit An object that must contain:
  • limit.offset, a number
  • limit.count, a number

It will return an object:

• selectQueryResult
  • selectQueryResult.spreadsheetId must be a string
  • selectQueryResult.range must be a string
  • selectQueryResult.rows must be an array

Background

The impetus for creating FunctionScript is simple: it stems from the initial vision of Autocode. We believe the modern web is missing a base primitive - the API. Daily, computer systems and developers around the planet make trillions of requests to perform specific tasks: process credit card payments with Stripe, send team messages via Slack, create SMS messages with Twilio. These requests are made primarily over HTTP: Hypertext Transfer Protocol. However, little to no "hypertext" is actually sent or received, these use cases have emerged in an ad hoc fashion as a testament to the power of the world wide web. Oftentimes, API standardization attempts have been presented as band-aids instead of solutions: requiring developers to jury rig a language, framework, markup language and hosting provider together just to get a simple "hello world" out the door.

By creating API development standards as part of a language specification instead of a framework, FunctionScript truly treats the web API as a base primitive of software development instead of an afterthought. This allows teams to be able to deliver high-quality APIs with the same fidelity as organizations like Stripe in a fraction of the time without requiring any additional tooling.

Table of Contents

1. Introduction
2. Why FunctionScript?
3. FunctionScript Examples
   1. All Available Types
4. Specification
   1. FunctionScript Resource Definition
   2. Context Definition
   3. Parameters
      1. Constraints
      2. Types
      3. Type Conversion
      4. Nullability
   4. FunctionScript Resource Requests
      1. Context
      2. Errors
         1. ClientError
         2. ParameterError
            1. Details: Required
            2. Details: Invalid
         3. FatalError
         4. RuntimeError
         5. ValueError
5. FunctionScript Server and Gateway: Implementation
6. Acknowledgements

Introduction

To put it simply, FunctionScript defines semantics and rules for turning exported JavaScript (Node.js) functions into strongly-typed, HTTP-accessible web APIs. In order to use FunctionScript, you'd set up your own FunctionScript Gateway or you would use an existing FunctionScript-compliant service like Autocode.

FunctionScript allows you to turn something like this...

// hello_world.js

/**
* My hello world function!
*/
module.exports = (name = 'world') => {

  return `hello ${name}`;

};

Into a web API that can be called over HTTP like this (GET):

https://$user.api.stdlib.com/service@dev/hello_world?name=joe

Or like this (POST):

{
  "name": "joe"
}

And gives a result like this:

"hello joe"

Or, when a type mismatch occurs (like {"name":10}):

{
  "error": {
    "type":"ParameterError"
    ...
  }
}

Why FunctionScript?

FunctionScript is intended primarily to provide a scaffold to build and deliver APIs easily. It works best as a part of the Autocode platform which consumes the FunctionScript API definitions, hosts the code, generates documentation from the definitions, and automatically handles versioning and environment management. The reason we've open sourced the language specification is so that developers have an easier time developing against the highly modular API ecosystem we've created and can contribute their thoughts and requests.

You can break down the reason for the development of FunctionScript into a few key points:

• Modern developers and people being introduced to software development for the first time are often trying to build web-native scripts. It is exceedingly difficult to go from "zero to API" in less than a few hours, writing code is just the first step of many. We'd like it to be the first and only step.

• No true standards around APIs have ever been built or enforced in a rigorous manner across the industry. Primarily, opinions around SOAP, REST and GraphQL requests have been built into frameworks and tools instead of a language specification, which has artificially inflated the cognitive overhead required to ship functional web-based software.

• Companies like Stripe and Twilio which have built and enforced their own API development paradigms internally have unlocked massive developer audiences in short timeframes, indicating the power of treating web APIs as a first-class citizen of development.

• Serverless computing, specifically the Function-as-a-Service model of web-based computation, has made API development significantly more accessible but has not brought us over the "last-mile" hump.

• JavaScript, specifically Node.js, is an ideal target for API development standardization due to its accessibility (front-end and back-end), growth trajectory, and flexibility. Most new developers are introduced to JavaScript out of necessity.

• As opposed to something like TypeScript, FunctionScript helps newer entrants to software development by extending JavaScript with very little overhead. It adds types around only the HTTP interface, leaving the majority of the language footprint untouched but strengthening the "weakest" and least predictable link in the development chain: user input.

With FunctionScript, it's our goal to develop a language specification for building APIs that automatically provides a number of necessary features without additional tooling:

• Standardized API Calling Conventions (HTTP)
• Type-Safety Mechanisms at the HTTP -> Code Interface
• Automatically Generated API Documentation

FunctionScript Examples

We'll be updating this section with examples for you to play with and modify on your own.

All Available Types

Here's an example of a hypothetical createUser.js function that can be used to create a user resource. It includes all available type definitions.

/**
* @param {integer} id ID of the User
* @param {string} username Name of the user
* @param {number} age Age of the user
* @param {float} communityScore Community score (between 0.00 and 100.00)
* @param {object} metadata Key-value pairs corresponding to additional user data
* @ {string} createdAt Created at ISO-8601 String. Required as part of metadata.
* @ {?string} notes Additional notes. Nullable (not required) as part of object
* @param {array} friendIds List of friend ids
* @ {integer} friendId ID of a user (forces array to have all integer entries)
* @param {buffer} profilePhoto Base64-encoded filedata, read into Node as a Buffer
* @param {enum} userGroup The user group. Can be "USER" (read as 0) or "ADMIN" (read as 9)
*   ["USER", 0]
*   ["ADMIN", 9]
* @param {boolean} overwrite Overwrite current user data, if username matching
* @returns {object.http} successPage API Returns an HTTP object (webpage)
*/
module.exports = async (id = null, username, age, communityScore, metadata, friendsIds = [], profilePhoto, userGroup, overwrite = false) => {

  // NOTE: id, friendIds and overwrite will be OPTIONAL as they have each been
  //       provided a defaultValue

  // Implementation-specific code here

  // API Output
  // NOTE: Note that because "object.http" was specified, this MUST follow the
  //       object.http schema: headers, statusCode, body

  return {
    headers: {'Content-Type': 'text/html'},
    statusCode: 200,
    body: Buffer.from('Here is a success message!')
  };

};

Specification

FunctionScript Resource Definition

A FunctionScript definition is a JSON output, traditionally saved as a definition.json file, generated from a JavaScript file, that respects the following format.

Given a function like this (filename my_function.js):

// my_function.js

/**
* This is my function, it likes the greek alphabet
* @param {String} alpha Some letters, I guess
* @param {Number} beta And a number
* @param {Boolean} gamma True or false?
* @returns {Object} some value
*/
module.exports = async (alpha, beta = 2, gamma, context) => {
  /* your code */
};

The FunctionScript parser will generate a definition.json file that looks like the following:

{
  "name": "my_function",
  "format": {
    "language": "nodejs",
    "async": true
  },
  "description": "This is my function, it likes the greek alphabet",
  "bg": {
    "mode": "info",
    "value": ""
  },
  "context": null,
  "params": [
    {
      "name": "alpha",
      "type": "string",
      "description": "Some letters, I guess"
    },
    {
      "name": "beta",
      "type": "number",
      "defaultValue": 2,
      "description": "And a number"
    },
    {
      "name": "gamma",
      "type": "boolean",
      "description": "True or false?"
    }
  ],
  "returns": {
    "type": "object",
    "description": "some value"
  }
}

A definition must implement the following fields;

Field	Definition
name	A user-readable function name (used to execute the function), must match /[A-Z][A-Z0-9_]*/i
format	An object requiring a language field, along with any implementation details
description	A brief description of what the function does, can be empty ("")
bg	An object containing "mode" and "value" parameters specifying the behavior of function responses when executed in the background
params	An array of NamedParameters, representing function arguments
returns	A Parameter without a defaultValue representing function return value

Context Definition

If the function does not access execution context details, this should always be null. If it is an object, it indicates that the function does access context details (i.e. remoteAddress, http headers, etc. - see Context).

This object does not have to be empty, it can contain vendor-specific details; for example "context": {"user": ["id", "email"]} may indicate that the execution context specifically accesses authenticated user id and email addresses.

Parameters

Parameters have the following format;

Field	Required	Definition
name	NamedParameter Only	The name of the Parameter, must match /[A-Z][A-Z0-9_]*/i
type	yes	A string representing a valid FunctionScript type
description	yes	A short description of the parameter, can be empty string ("")
defaultValue	no	Must match the specified type. If type is not provided, this parameter is required

Types

As FunctionScript interfaces with "userland" (user input), a strongly typed signature is enforced for all inbound parameters. The following is a list of supported FunctionScript types.

Type	Definition	Example Input Values (JSON)
boolean	True or False	true or false
string	Basic text or character strings	"hello", "GOODBYE!"
number	Any double-precision Floating Point value	2e+100, 1.02, -5
float	Alias for number	2e+100, 1.02, -5
integer	Subset of number, integers between -2^53 + 1 and +2^53 - 1 (inclusive)	0, -5, 2000
object	Any JSON-serializable Object	{}, {"a":true}, {"hello":["world"]}
object.http	An object representing an HTTP Response. Accepts headers, body and statusCode keys	{"body": "Hello World"}, {"statusCode": 404, "body": "not found"}, {"headers": {"Content-Type": "image/png"}, "body": Buffer.from(...)}
array	Any JSON-serializable Array	[], [1, 2, 3], [{"a":true}, null, 5]
buffer	Raw binary octet (byte) data representing a file	{"_bytes": [8, 255]} or {"_base64": "d2h5IGRpZCB5b3UgcGFyc2UgdGhpcz8/"}
any	Any value mentioned above	5, "hello", []
enum	An enumeration that maps input strings to values of your choosing	"STRING_OF_YOUR_CHOICE"

Type Conversion

The buffer type will automatically be converted from any object with a single key-value pair matching the footprints {"_bytes": []} or {"_base64": ""}.

Otherwise, parameters provided to a function are expected to match their defined types. Requests made over HTTP via query parameters or POST data with type application/x-www-form-urlencoded will be automatically converted from strings to their respective expected types, when possible (see FunctionScript Resource Requests below):

Type	Conversion Rule
boolean	"t" and "true" become true, "f" and "false" become false, otherwise do not convert
string	No conversion
number	Determine float value, if NaN do not convert, otherwise convert
float	Determine float value, if NaN do not convert, otherwise convert
integer	Determine float value, if NaN do not convert, may fail integer type check if not in range
object	Parse as JSON, if invalid do not convert, object may