The Modus 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 defined in your app’s manifest. Any attempt to access an arbitrary URL, for a host not defined in your app’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.

​
Import

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 early users. Open an issue if you have ideas on what would make Modus even more powerful for your next app!

​
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
requestOrUrl
string | Request
required

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.

options
RequestOptions

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.

Content.from(value)

Creates a new Content object from the given value.

data
ArrayBuffer

The raw binary content data.

text()

Interprets the content as a UTF-8 encoded string, and returns it as a string value.

json<T>()

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.

class Header {
  name: string;
  values: string[];
}

Represents an HTTP request or response header.

name
string

The name of the header.

values
string[]

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.

Headers.from(value)

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.
append(name, value)

Appends a new header with the given name and value to the collection.

entries()

Returns a string[][], where each inner array contains a header name and value.

get(name)

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.

new http.Request(url, options?)

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.

Request.clone(request, options)

Creates a new Request object by cloning the given request and applying the options to it.

url
string

The fully qualified URL of the request, including the protocol. For example, "https://example.com".

method
string

The HTTP method of the request. For example, "GET", "POST", "PUT", or "DELETE".

headers
Headers

The HTTP headers of the request, as a Headers object.

body
ArrayBuffer

The raw binary content data of the request body.

text()

Interprets the request body as a UTF-8 encoded string, and returns it as a string value.

json<T>()

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.

method
string | null

The HTTP method of the request. For example, "GET", "POST", "PUT", or "DELETE". If null (the default), the request uses the GET method.

headers
Headers

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.

body
Content | null

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.

status
u16

The HTTP response status code, such as 200 for success.

statusText
string

The HTTP response status text associated with the status code, such as "OK" for success.

headers
Headers

The HTTP headers received with the response, as a Headers object.

body
ArrayBuffer

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.

text()

Interprets the response body content as a UTF-8 encoded string, and returns it as a string value.

json<T>()

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.

Was this page helpful?

GraphQLModels