HTTP
Access external HTTP endpoints from your functions.
Hypermode’s HTTP API allows you to securely call and fetch data from an HTTP endpoint.
It’s similar to the HTTP fetch
API used in JavaScript,
but with some modifications to work with Hypermode Functions.
As a security measure, you can only call HTTP endpoints that you’ve defined in your project’s manifest. Any attempt to access an arbitrary URL, for a host not defined in your project’s manifest, results in an error.
Additionally, you should use placeholders for host secrets in the manifest, rather than hardcoding them in your functions. Enter the values for each hosts’ secrets via the Hypermode UI. This ensures that your secrets are securely stored, aren’t committed to your repository, and aren’t visible or accessible from your functions code.
Example project
For your reference, A complete example for using the HTTP API is available on GitHub in the
hypermodeinc/functions-as
repository, at /examples/http.
Import from the SDK
To begin, import the http
namespace from the SDK:
HTTP APIs
The APIs in the http
namespace are below, organized by category.
We’re constantly introducing new APIs through ongoing development with build partners. Let’s chat about what would make the Functions SDK even more powerful for your next use case!
Functions
fetch
Invoke an HTTP endpoint to retrieve data or trigger external action.
Returns a Response
object with the HTTP response data.
http.fetch(
requestOrUrl: string | Request,
options: RequestOptions = new RequestOptions(),
): Response
Either a URL string
or a Request
object, describing the HTTP request to make.
If a string
, the operation uses the GET
HTTP method with no headers other than
those defined in the manifest entry of the host.
Each request must match to a host entry in the manifest, using the baseUrl
field. The request URL passed to the fetch
function (or via a Request
object) must start with the manifest entry’s baseUrl
value to match.
A RequestOptions
object with additional options for the
request, such as the HTTP method, headers, and body.
Objects
Content
class Content {
static from(value: any): Content;
readonly data: ArrayBuffer;
text(): string;
json<T>(): T;
}
Represents content used in the body of an HTTP request or response.
Creates a new Content
object from the given value.
The raw binary content data.
Interprets the content as a UTF-8 encoded string, and returns it as a string
value.
Interprets the content as a UTF-8 encoded string containing JSON in the shape
of type T
, and returns it as a value of type T
.
Header
class Header {
name: string;
values: string[];
}
Represents an HTTP request or response header.
The name of the header.
An array of values for the header. Typically a header has a single value, but some headers can have multiple values.
Headers
class Headers {
static from(
value: string[][] | Map<string, string> | Map<string, string[]>,
): Headers;
append(name: string, value: string): void;
entries(): string[][];
get(name: string): string | null;
}
Represents a collection of HTTP headers.
Creates a new Headers
object from the given value
object.
The value
object must be one of the following types:
- A
string[][]
, where each inner array contains a header name and value. - A
Map<string, string>
, where the keys are header names and the values are header values. - A
Map<string, string[]>
, where the keys are header names and the values are arrays of header values.
Appends a new header with the given name
and value
to the collection.
Returns a string[][]
, where each inner array contains a header name and
value.
Returns the value of the header with the given name
, or null
if the header
doesn’t exist. If there are multiple values for the header, this function
concatenates them with a comma to form a single string.
Request
class Request {
constructor(url: string, options?: RequestOptions);
static clone(request: Request, options: RequestOptions): Request;
readonly url: string;
readonly method: string;
readonly headers: Headers;
readonly body: ArrayBuffer;
text(): string;
json<T>(): T;
}
Represents an HTTP request to make.
Creates a new Request
object with the given url
and options
.
The required url
parameter must be a fully qualified URL of the request, including the protocol.
For example, "https://example.com"
.
The optional options
parameter is a RequestOptions
object that’s used to set
the HTTP method, headers, and body if needed.
Creates a new Request
object by cloning the given request
and applying the
options
to it.
The fully qualified URL of the request, including the protocol. For example,
"https://example.com"
.
The HTTP method of the request. For example, "GET"
, "POST"
, "PUT"
, or
"DELETE"
.
The HTTP headers of the request, as a Headers
object.
The raw binary content data of the request body.
Interprets the request body as a UTF-8 encoded string, and returns it as a
string
value.
Interprets the request body as a UTF-8 encoded string containing JSON in the
shape of type T
, and returns it as a value of type T
.
RequestOptions
class RequestOptions {
method: string | null;
headers: Headers;
body: Content | null;
}
Options for the HTTP request.
The HTTP method of the request. For example, "GET"
, "POST"
, "PUT"
, or
"DELETE"
. If null
(the default), the request uses the GET
method.
The HTTP headers of the request, as a Headers
object.
By default, the RequestOptions
contains an empty Headers
object
which you can add headers to using the append
method.
Content to pass in the request body, as a Content
object,
or null
(the default) if there is no body to pass.
It’s generally recommended to supply a Content-Type
header for any requests
that have a body.
Response
class Response {
readonly status: u16;
readonly statusText: string;
readonly headers: Headers;
readonly body: ArrayBuffer;
readonly ok: bool;
text(): string;
json<T>(): T;
}
Represents the response received from the HTTP server.
The HTTP response status code, such as 200
for success.
The HTTP response status text associated with the status code, such as "OK"
for success.
The HTTP headers received with the response, as a Headers
object.
The raw binary content data of the response body.
The response body isn’t normally read directly. Instead, use the text
or
json
functions. You should only read the body
directly if you expect to
receive binary data in the response.
Interprets the response body content as a UTF-8 encoded string, and returns it
as a string
value.
Interprets the response body content as a UTF-8 encoded string containing JSON
in the shape of type T
, and returns it as a value of type T
.