While each Modus SDK offers similar capabilities, the APIs and usage may vary between languages.

Modus HTTP APIs documentation is available on the following pages:

The Modus HTTP APIs allow 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 Modus.

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 connection not defined in your app’s manifest, results in an error.

Additionally, you should use placeholders for connection secrets in the manifest, rather than hardcoding them in your functions. Enter the values for each connections’ secrets via environment variables or 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:

import { http } from "@hypermode/modus-sdk-as"

​
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. Please 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.

function 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 connection.

Each request must match to a connection 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.

​
Types

​
Content

Represents content used in the body of an HTTP request or response.

class Content {
  static from<T>(value: T): Content
  readonly data: ArrayBuffer
  bytes(): Uint8Array
  text(): string
  json<T>(): T
}
​
Content.from(value)

Creates a new Content object from the given value.

The value can be of any type that’s JSON serializable, including strings, numbers, boolean values, arrays, maps, and custom objects decorated with @json.

If the value is a string, an ArrayBuffer, or a Uint8Array it’s sent as-is, without JSON serialization.

​
data
ArrayBuffer

The raw binary content data buffer.

​
bytes()

Returns the binary content data as a Uint8Array.

​
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.

Represents an HTTP request or response header.

class Header {
  name: string
  values: string[]
}
​
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

Represents a collection of HTTP 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
}
​
Headers.from(value)

Creates a new Headers object from the given value.

The value 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

Represents an HTTP request to make.

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
  bytes(): Uint8Array
  text(): string
  json<T>(): T
}
​
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 buffer of the request body.

The request body isn’t normally read directly. Instead, use the bytes, text or json functions.

​
bytes()

Returns the binary content data of the request body as a Uint8Array.

​
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

Options for the HTTP request.

class RequestOptions {
  method: string | null
  headers: Headers
  body: Content | null
}
​
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

Represents the response received from the HTTP server.

class Response {
  readonly status: u16
  readonly statusText: string
  readonly headers: Headers
  readonly body: ArrayBuffer
  readonly ok: bool
  bytes(): Uint8Array
  text(): string
  json<T>(): T
}
​
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 buffer of the response body.

The response body isn’t normally read directly. Instead, use the bytes, text or json functions.

​
ok
bool

A boolean value indicating whether the response was successful. It’s true if the status code is in the range 200-299, and false otherwise.

​
bytes()

Returns the binary content data of the response body as a Uint8Array.

​
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?

Suggest edits
GraphQLLocal Time