Endpoint

Introduction

Endpoint invocations are declarative calls where the path names the action and the body carries the data. In essence, endpoints are about intent and do not enforce structure or how resources are accessed. Like calling functions, invoking endpoints feels more like writing code and less like negotiating with a spec committee.

Requirements language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals, as shown here.

HTTP Method

Endpoints MUST be invoked using the HTTP POST method. Servers MUST NOT require any other method for invocation, and clients MUST NOT use any other method.

Redirection

Clients MUST NOT follow redirection responses. A redirection (any 3xx status code) is treated like any other status code outside this specification: the client surfaces it without following the Location header. See Status codes.

Headers

The following HTTP headers are referenced throughout the Web Function specifications. Conditional headers apply only when the noted flag is active.

Body

The body of the request MUST be a valid JSON object. The body of the response MAY be any valid JSON value:

• object
• array
• number
• string
• boolean
• null

Status codes

Only two status codes carry protocol-level meaning:

• 200: Success. The request was processed successfully. The response body carries the return value.
• 400: Bad request. The payload sent by the client is incorrect or malformed. The response body SHOULD contain details about the error and MUST adhere to all protocol requirements for headers and body.

Any other status code is outside the scope of this specification: its body, headers, and semantics are not defined here, and a client MUST NOT interpret such a response as a successful invocation. Rather than discarding the response or fabricating a generic error, a client SHOULD raise an exception (or otherwise surface an error) that preserves the original HTTP status code, so the caller can inspect and handle it. This applies equally to redirection responses (see Redirection) and to any status produced by intermediaries such as proxies, gateways, or load balancers (for example 401, 429, or 5xx).

Fundamentally, the status code is the primary signal of whether the request was processed successfully.

Path format guidelines

Endpoints MAY be accessed using any valid path format. The last part of the path, following the last forward slash, is considered to be the function name. Consider using dash case (illustratively known as kebab-case) for all parts of the path, including the function name. Avoid including IDs or other parameters in the path and instead, encode them in the request's body.

Cross-origin requests (CORS)

Because endpoints are invoked with POST and Content-Type: application/json, browser clients trigger a CORS preflight (an OPTIONS request) before the actual invocation. A server that intends to serve browser-based clients MUST implement CORS: it MUST answer preflight OPTIONS requests and return the appropriate Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers response headers.

The preflight OPTIONS request is part of the CORS mechanism and is not an endpoint invocation; it is therefore exempt from the POST-only rule above.

Spec extensions

The following are extensions to the core endpoint specification. They are not required, but can be activated via package flags. The package specification is itself not mandatory but greatly improves discoverability.

• Package
• Versioning (versioned)
• Pipelining
• Authentication (bearer_auth)
• Pagination (paginated)
• Event (event_source)
• Error (error_triple)