Web Function - Package

Introduction

The Web Function Package specification simplifies endpoint interaction by standardizing their description and access. This defined structure ensures all endpoints are consistent, discoverable, and self-documented.

Package definition

A package is a JSON object that contains the following keys:

Key and type	Description
base_url string	Required. Base URL for the package. MUST use the HTTP or HTTPS scheme.
event_source_url string	Optional. An event source URL from which to receive server-sent-events. See the event specification for more information.
pipeline_url string	Optional. A function pipelining URL. See the pipelining specification for more information.
name string	Optional. The name of the package.
flags array of strings	Optional. List of package flags. See the available flags section below for a complete list of flags available at the package level.
docs string	Optional. Top-level documentation for the package. MUST be formatted as markdown.
endpoints array of objects	Required. An array of endpoint definitions, as described below.
events array of objects	Optional. An array of events definitions, as described below. See the event specification for more information.
errors array of objects	Optional. A list of common ERROR_CODEs that can be returned by any endpoints in this package. Note that clients SHOULD only refer to this list if an endpoint uses the `error_triple` flag. See the error specification for more information.

Endpoint definition

Each element in the endpoints array is an object that contains the following keys:

Key and type	Description
name string	Required. Suffix for the endpoint URL, appended to the PACKAGE_BASE_URL to form the full endpoint URL. Overloading is supported. This means that two endpoints with the same name but different arguments should be supported by clients.
returns array of strings	Required. List of possible JSON types returned by the endpoint. Allowed values are: `object`, `array`, `string`, `number`, `boolean`, or `null`.
hints array of strings	Optional. List of hints for the endpoint. See the hints section below for a complete list of allowed hints. Note that the appropriate hint will be decided based on the base return type, which means multiple hints for the same base type cannot be provided.
flags array of strings	Optional. List of endpoint flags. See the available flags section below for a complete list of flags available at the endpoint level.
group string	Optional. A name used to categorize or group similar endpoints together. This should be used by documentation tools to organize related endpoints.
docs string	Optional. Documentation for the endpoint. MUST be formatted as markdown.
errors array of objects	Optional. A list of specific ERROR_CODE that can be returned by this endpoint. Note that clients SHOULD only refer to this list if an endpoint uses the `error_triple` flag. See error for more information.
arguments array of objects	Required. Arguments required by the endpoint, as described below. If no arguments are required, the array should be empty.
attributes array of objects	Optional. Attributes of the object returned by the endpoint, as described below. If the `type` is something else than `object` this element can be absent.

Event definition

Each element in the events array is an object that contains the following keys:

Key and type	Description
name string	Required. The name of the event.
group string	Optional. A name used to categorize or group similar events together. This should be used by documentation tools to organize related events.
docs string	Optional. Documentation for the event. MUST be formatted as markdown.
attributes array of objects	Required. Attributes in the event object, as described below.

Argument definition

Each element in the arguments array is an object that contains the following keys:

Key and type	Description
name string	Required. Name of the argument.
type string	Required. JSON type of the argument (one of: `object`, `array`, `string`, `number`, `boolean`).
hint string	Optional. A hint for the argument. See the hints section below for a complete list of allowed hints.
group string	Optional. A name used to categorize or group similar arguments together. This should be used by documentation tools to organize related arguments.
choices array	Optional. An array specifying the exact, case-sensitive values that are permitted for this argument. Each value in the choices array must conform to the data type specified in the argument's type key. Note that if the argument type is `array`, choices may contain strings or numbers representing the allowed values that can be included in the array.
flags array of strings	Optional. List of argument flags. See the available flags section below for a complete list of flags available at the argument level.
docs string	Optional. Description of the argument. MUST be formatted as markdown.

Attribute definition

Each element in the attribute array is an object that contains the following keys:

Key and type	Description
name string	Required. Name of the attribute.
type string	Required. JSON type of the attribute (one of: `object`, `array`, `string`, `number`, `boolean`).
hint string	Optional. A hint for the attribute. See the hints section below for a complete list of allowed hints.
values array	Optional. An array specifying the exact, case-sensitive values that could be present in this attribute. Each value in the values array must conform to the data type specified in the attribute's type key. Note that if the attribute type is `array`, values may contain strings or numbers representing the allowed values that could be part of the array.
flags array of strings	Optional. List of attribute flags. See the available flags section below for a complete list of flags available at the attribute level.
docs string	Optional. Description of the attribute. MUST be formatted as markdown.

Error definition

Each element in the error array is an object that contains the following keys:

Key and type	Description
code string	Required. Machine readable code for the error.
docs string	Optional. Description of the error. The description SHOULD focus on explaining all the situations in which this error will arise. MUST be formatted as markdown.

Available flags

Name	Type	Description
package	Endpoint	Indicates the endpoint returns another package definition.
event_source	Endpoint	Indicates the endpoint returns an event source URL. See the event specification for more information.
error_triple	Endpoint	Indicates the endpoint adheres to the error response structure as per the error specification.
bearer_auth	Endpoint	Indicates the endpoint requires authentication via a bearer token.
capture_bearer	Endpoint	Indicates the endpoint will return a bearer token in its response. See the authentication specification for more information.
paginated	Endpoint	Indicates the endpoint supports pagination.
private	Endpoint	Indicates the endpoint is not part of the public API and should not be exposed to clients.
required	Argument	Indicates if the argument is mandatory.
nullable	Attribute	Indicates if the attribute could be `null`.

Hints

A hint provides additional information about the data type of an endpoint, argument, or attribute. They are particularly useful for languages with strict typing or for providing more specific constraints than the base JSON types.

Hint	Base JSON Type	Explanation
u32	number	Unsigned 32-bit integer.
u64	number	Unsigned 64-bit integer.
i32	number	Signed 32-bit integer.
i64	number	Signed 64-bit integer.
f32	number	32-bit floating point number.
f64	number	64-bit floating point number.
timestamp	number	A UNIX timestamp (seconds since the epoch).
date	string	A date string in ISO 8601 format (e.g., YYYY-MM-DD).
time	string	A time string in ISO 8601 format (e.g., HH:MM:SS).
datetime	string	A date-time string in ISO 8601 format.
uuid	string	A Universally Unique Identifier.
base64	string	A Base64 encoded string.
email	string	An email address.
phone	string	A phone number in E.164 format.
url	string	A Uniform Resource Locator.
uri	string	A Uniform Resource Identifier.
ipv4	string	An IPv4 address.
ipv6	string	An IPv6 address.
hostname	string	A valid hostname as defined by RFC 1123.

Validation requirements

Each package MUST pass the following validations:

The base URL MUST be valid as per RFC 3986.
All specified types and flags MUST match defined constraints.

Example

A simple example of a Web Function Package defining a single endpoint might look like this:

{
  "base_url": "https://api.example.com",
  "name": "ExamplePackage",
  "flags": [],
  "docs": "This package defines endpoints for Example API.",
  "errors": [],
  "endpoints": [
    {
      "name": "find-user-by",
      "returns": ["object"],
      "flags": [],
      "group": "users",
      "docs": "Retrieves user data.",
      "errors": [],
      "arguments": [
        {
          "name": "id",
          "type": "string",
          "choices": [],
          "flags": ["required"],
          "docs": "Identifier of the user."
        }
      ]
    }
  ]
}

Retrieval

Static file. A Web Function Package MAY be distributed as a static file.
Dynamically generated. A Web Function Package MAY be dynamically generated by a web application. This allows the package to be customized in real-time based on the request parameters or the state of the application at the time of the request. This makes it particularly useful for scenarios where the configuration of the package needs to adapt to varying circumstances or user-specific data.
Invocation response. A Web Function Package MAY also be retrieved as the response from a Web Function Endpoint invocation. This allows for a dynamic and recursive discovery mechanism where endpoints themselves return packages as part of their operation. This method supports complex scenarios where packages are interdependent or where the structure of available APIs can change.