Web Function First draft
Endpoint Package Error Authentication Pagination
CORE SPECIFICATION

Endpoint

A minimal specification for designing API endpoints that is flexible, familiar, and fun! Escape the constraints of existing architectural styles and adopt an approach that feels as intuitive as everyday functions.

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.

HTTP Method

Only POST requests are permitted for invoking endpoints.

Redirection

Redirects are prohibited. Clients must not follow redirection responses.

Headers

  • Content-Type: Requests and responses must include the following header: 
    Content-Type: application/json
  • Accept: Requests must include the following header: 
    Accept: application/json

Body

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

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

Status codes

Only the following status codes are permitted:

  • 200: Success. The request was processed successfully.
  • 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.

For any other status codes, the entire response, including its code, headers, and body, can be discarded by the client. In such cases, the client MAY return a generic error message indicating a malformed response.

Fundamentally, the status code is the primary signal that the request was processed successfully or not.

Path format guidelines

Endpoints can 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.

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.