Serving an HTTPS request
Overview
Canisters can serve or handle an incoming HTTPS request using the HTTP Gateway Protocol.
This allows developers to host web applications and APIs from a canister.
How it works
An HTTPS request from a client gets intercepted by the HTTP Gateway Protocol, which identifies the target canister and encodes the request in Candid. This encoded request is then sent to the canister for processing. Once processed, the canister replies with an HTTPS response. Finally, the HTTP Gateway Protocol decodes the response using Candid and sends it back to the client, completing the communication loop.
For detailed information on how it works, please refer to the HTTP Gateway Protocol specification.
How to make a request
The following example returns 'Hello, World!' in the body at the /hello
endpoint.
- Motoko
- Rust
- Typescript
- Python
import Buffer "mo:base/Buffer";
type HeaderField = (Text, Text);
type HttpResponse = {
status_code: Nat16;
headers: [HeaderField];
body: Blob;
};
type HttpRequest = {
method: Text;
url: Text;
headers: [HeaderField];
body: Blob;
};
public query func http_request(req: HttpRequest): async (HttpResponse) {
let path = removeQuery(req.url);
if(path == "/hello") {
return {
status_code = 200,
headers = [],
body = Buffer.from('Hello, World!'),
};
};
return {
body = Text.encodeUtf8("404 Not found :");
headers = [];
status_code = 404;
};
};
type HeaderField = (String, String);
struct HttpResponse {
status_code: u16,
headers: Vec<HeaderField>,
body: Cow<'static, Bytes>,
}
struct HttpRequest {
method: String,
url: String,
headers: Vec<(String, String)>,
body: ByteBuf,
}
#[query]
fn http_request(req: HttpRequest) -> HttpResponse {
let path = req.url.path();
if path == "/hello" {
HttpResponse {
status_code: 200,
headers: Vec::new(),
body: b"hello, world!".to_vec(),
streaming_strategy: None,
upgrade: None,
}
} else {
HttpResponse {
status_code: 404,
headers: Vec::new(),
body: b"404 Not found :".to_vec(),
streaming_strategy: None,
upgrade: None,
}
}
}
import {
blob,
bool,
Canister,
Func,
nat16,
None,
Opt,
query,
Record,
text,
Tuple,
Variant,
Vec
} from 'azle';
type HeaderField = [text, text];
const HeaderField = Tuple(text, text);
const HttpResponse = Record({
status_code: nat16,
headers: Vec(HeaderField),
body: blob,
});
const HttpRequest = Record({
method: text,
url: text,
headers: Vec(HeaderField),
body: blob,
});
export default Canister({
http_request: query([HttpRequest], HttpResponse, (req) => {
const path = req.url.pathname;
if(path == "/hello") {
return {
status_code: 200,
headers: [],
body: Buffer.from('hello, world!')
};
} return {
body: Text.encodeUtf8("404 Not found :");
headers: [];
status_code:404;
}
})
});
To learn more about serving an HTTPS request in Typescript, refer to the Azle book reference on incoming HTTPS requests.
from kybra import blob, Func, nat16, Opt, query, Query, Record, Tuple, Variant, Vec
class HttpRequest(Record):
method: str
url: str
headers: Vec["Header"]
body: blob
class HttpResponse(Record):
status_code: nat16
headers: Vec["Header"]
body: blob
Header = Tuple[str, str]
@query
def http_request(req: HttpRequest) -> HttpResponse:
path = req.url.path
if path == "/hello":
return {
"status_code": 200,
"headers": [],
"body": Buffer.from_text("hello, world!").encode("utf-8"),
}
else:
return {
"status_code": 404,
"headers": [],
"body": b"404 Not found :",
}
To learn more about serving an HTTPS request in Python, refer to the Kybra book reference on incoming HTTPS requests.
Additional examples
The HTTPS counter project is an example in Motoko of a 'counter' application that uses the http_request
method to read the current counter value or access some pre-stored data and the http_request_update
method to increment the counter and retrieve the updated value.