Skip to main content

How to use HTTP outcalls: Intro

This guide shoes how to use the HTTPS outcalls feature of the IC. This feature allows smart contracts to directly make calls to HTTP(S) servers external to the blockchain and use the response in the further processing of the smart contract, without the need of oracles.

Key concepts​

Methods supported​

The feature currently supports GET, HEAD, and POST methods for HTTP requests.

IC management canister​

  • The IC management canister - In order for a canister to use HTTPS outcalls, it needs to call into the system API of the IC. Canisters can call into the system API by sending messages to the IC management canister. The intent is to make using the system API as simple as if it were just another canister. Management canister is evoked by using the identifier "aaaaa-aa".

The IC management canister is just a facade; it does not actually exist as a canister (with isolated state, Wasm code, etc.).

Cycles​

  • Cycles used to pay for the call must be explicitly transferred with the call, i.e., they are not deducted from the caller's balance implicitly (e.g., as for inter-canister calls).

The API for sending HTTP outcalls​

As per the Internet Computer interface specification, a canister can use the http_request method by following construction:

The request​

The following parameters should be supplied for in the request:

  • url: the requested URL. The URL must be valid according to https://www.ietf.org/rfc/rfc3986.txt[RFC-3986] and its length must not exceed 8192. The URL may specify a custom port number.

  • max_response_bytes: optional; specifies the maximal size of the response in bytes. If provided, the value must not exceed 2MB (2,000,000B). The call will be charged based on this parameter. If not provided, the maximum of 2MB will be used.

  • method: currently, only GET, HEAD, and POST are supported.

  • headers: list of HTTP request headers and their corresponding values.

  • body: optional; the content of the request's body.

  • transform: an optional function that transforms raw responses to sanitized responses, and a byte-encoded context that is provided to the function upon invocation, along with the response to be sanitized. If provided, the calling canister itself must export this function.

The response​

The returned response (and the response provided to the transform function, if specified) contains the following fields:

  • status: the response status (e.g., 200, 404).

  • headers: list of HTTP response headers and their corresponding values.

  • body: the response's body.

Sample code​

To see concrete examples of making GET and POSTrequests in Motoko and Rust see: