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:
- AssemblyScript HTTP APIs
- Go HTTP APIs(this page)
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 thehttp
package from the SDK:
HTTP APIs
The APIs in thehttp
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 aResponse
object with the HTTP response data.
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.An optional pointer to a
RequestOptions
object with
additional options for the request, such as the HTTP method, headers, and
body.NewContent
Creates a newContent
object from the given value
, and returns a
pointer to it.
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 newHeaders
object from the given value
, and returns a
pointer to it.
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 newRequest
object with the given url
and options
,
and returns a pointer to it.
The fully qualified URL of the request, including the protocol. For example,
"https://example.com"
.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.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:Header
Represents an HTTP request or response header.The name of the header.
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.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.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 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:RequestOptions
Options for the HTTP request.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.
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 is generally recommended to supply a
Content-Type
header for any requests
that have a body.Response
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 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: