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.

In a future version of Modus, we’ll support Go’s standard net/http package for making HTTP requests. However, that’s currently not supported due to technical limitations.

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 package from the SDK:

import "github.com/hypermodeinc/modus/sdk/go/pkg/http"

​
HTTP APIs

The APIs in the http package 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.

func Fetch[T *Request | string](
  requestOrUrl T,
  options ...*RequestOptions
) (*Response, error)
​
requestOrUrl
*Request | string
required

Either a URL string or a pointer to 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

An optional pointer to a RequestOptions object with additional options for the request, such as the HTTP method, headers, and body.

​
NewContent

Creates a new Content object from the given value, and returns a pointer to it.

func NewContent(value any) *Content
​
value
required

The value to create the Content object from. Must be one of the following types:

  • A Content object, or a pointer to one.
  • A []byte of binary content, or a pointer to one.
  • A string of text content.
  • Any other object that’s JSON serializable. The content then becomes the JSON representation of the object.

​
NewHeaders

Creates a new Headers object from the given value, and returns a pointer to it.

func NewHeaders[T [][]string | map[string]string | map[string][]string](
  value T
) *Headers
​
value
[][]string | map[string]string | map[string][]string
required

The value object to create the Headers object from. Must be one of the following types:

  • A [][]string, where each inner slice 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 slices of header values.

​
NewRequest

Creates a new Request object with the given url and options, and returns a pointer to it.

func NewRequest(url string, options ...*RequestOptions) *Request
​
url
string
required

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

​
options
*RequestOptions

An optional pointer to a RequestOptions object that’s used to set the HTTP method, headers, and body if needed.

​
Types

​
Content

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

Use the NewContent function to create a new Content object.

type Content struct {
  // no exported fields
}

// methods
func (*Content) Bytes() []byte
func (*Content) Text() string
func (*Content) JSON(result any) error
​
Bytes()

Returns the binary content as a byte slice.

​
Text()

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

​
JSON(result any) error

Interprets the content as a UTF-8 encoded string containing JSON, and attempts to deserialize it into the result provided.

Pass the result as a pointer to an object matching the shape of the JSON. For example:

var data MyData
if err := content.JSON(&data); err != nil {
  // handle error
}

Represents an HTTP request or response header.

type Header struct {
  Name   string
  Values []string
}
​
Name
string

The name of the header.

​
Values
[]string

An slice 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.

Use the NewHeaders function to create a new Headers object.

type Headers struct {
  // no exported fields
}

// methods
func (*Headers) Append(name, value string)
func (*Headers) Entries() [][]string
func (*Headers) Get(name string) *string
​
Append(name, value)

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

​
Entries()

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

​
Get(name)

Returns the value of the header with the given name, or nil 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.

Use the NewRequest function to create a new Request object.

type Request struct {
  Url     string
  Method  string
  Headers *Headers
  Body    []byte
}

// methods
func (*Request) Clone(options ...*RequestOptions) *Request
func (*Request) Bytes() []byte
func (*Request) Text() string
func (*Request) JSON(result any) error
​
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 pointer to a Headers object.

​
Body
[]byte

The raw binary content data of the request body.

The request body isn’t normally read directly. Instead, use the Bytes, Text, or JSON methods.

​
Clone(options)

Clones the Request object, applies the options to the new object, and returns it.

​
Bytes()

Returns the binary content of the request body as a byte slice.

​
Text()

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

​
JSON(result any) error

Interprets the content of the request body as a UTF-8 encoded string containing JSON, and attempts to deserialize it into the result provided.

Pass the result as a pointer to an object matching the shape of the JSON. For example:

var data MyData
if err := request.JSON(&data); err != nil {
  // handle error
}

​
RequestOptions

Options for the HTTP request.

type RequestOptions struct {
  Method  string
  Headers any
  Body    any
}
​
Method
string

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

​
Headers

The HTTP headers of the request, which must be of one of the following types:

  • A Headers object, or a pointer to one.
  • A [][]string, where each inner slice 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 slices of header values.
​
Body
any

Content to pass in the request body. Must be one of the following types:

  • A Content object, or a pointer to one.
  • A []byte of binary content, or a pointer to one.
  • A string of text content.
  • nil 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.

type Response struct {
  Status     uint16
  StatusText string
  Headers    *Headers
  Body       []byte
}

// methods
func (*Response) Ok() bool
func (*Response) Bytes() []byte
func (*Response) Text() string
func (*Response) JSON(result any) error
​
Status
uint16

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 pointer to a Headers object.

​
Body
[]byte

The raw binary content data of the response body.

The response body isn’t normally read directly. Instead, use the Bytes, Text, or JSON methods.

​
Bytes()

Returns the binary content of the response body as a byte slice.

​
Text()

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

​
JSON(result any) error

Interprets the content of the response body as a UTF-8 encoded string containing JSON, and attempts to deserialize it into the result provided.

Pass the result as a pointer to an object matching the shape of the JSON. For example:

var data MyData
if err := response.JSON(&data); err != nil {
  // handle error
}

Was this page helpful?

Suggest edits
GraphQLLocal Time