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.
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.
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 Error Triple for more information.
endpoints array of objects	Required. An array of endpoint definitions, as described below.

Endpoint definition

Each element in the endpoints array are objects 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 string	Required. List of possible JSON types returned by the endpoint. Allowed values are: `object`, `array`, `string`, `number`, `boolean`, or `null`.
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.
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 Triple 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.

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`).
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.

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`).
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.

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.

Available flags

Name	Type	Description
markdown_docs	Package	Indicates that all docs values will be formatted as markdown.
package	Endpoint	Indicates the endpoint returns another package definition.
error_triple	Endpoint	Indicates the endpoint adheres to the error response structure as per the error triple specification.
bearer_auth	Endpoint	Indicates the endpoint requires authentication via a bearer token.
paginated	Endpoint	Indicates the endpoint supports pagination.
required	Argument	Indicates if the argument is mandatory.
nullable	Attribute	Indicates if the attribute could be `null`.

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.