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.