HTTPS
In AIUI, HTTPS is used for request-oriented communication over HTTP / HTTPS. The most common pattern is "send one request, then wait for the server response", but that does not mean the response body must always be consumed all at once.
If you are building configuration fetching, ordinary REST APIs, form submissions, or agent service calls, HTTPS is usually the first choice. When the server returns chunked data, you can also consume the response incrementally through the Response object returned by fetch().
Send a JSON request
Web
const response = await fetch('https://api.example.com/agent/chat', {
method: 'POST',
headers: {
'content-type': 'application/json',
},
body: JSON.stringify({
message: 'Summarize today\'s meeting for me',
}),
});
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}
const data = await response.json();
console.log(data);
wx
wx.request({
url: 'https://api.example.com/agent/chat',
method: 'POST',
header: {
'content-type': 'application/json',
},
data: {
message: 'Summarize today\'s meeting for me',
},
success(res) {
console.log(res.statusCode, res.data);
},
fail(error) {
console.error(error);
},
});
Read a streaming text response with fetch
const response = await fetch('https://api.example.com/agent/stream');
const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');
let text = '';
while (true) {
const { value, done } = await reader.read();
if (done) {
break;
}
text += decoder.decode(value, { stream: true });
}
text += decoder.decode();
console.log(text);
Read Packaged Assets and Inspect a Request
GET/HEAD Fetch requests can read paths rooted in a full application's package. /assets/route.gpx and file:///assets/route.gpx access the same packaged resource, not arbitrary device files. Use explicit https:// URLs for remote API endpoints.
const response = await fetch('/assets/route.gpx');
const route = await response.text();
console.log(route);
const request = new Request('https://api.example.com/order', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ quantity: 2 }),
});
console.log(await request.clone().json());
console.log(request.bodyUsed); // false
await fetch(request);
Request convenience readers and stream reads share consumption state. To inspect a body and still send it, clone before reading. Locked or consumed bodies cannot be read or cloned again.
Upload a File and Form Fields
Use File and FormData to submit text fields and files together:
const attachment = new File(['AIUI 0.18'], 'release.txt', {
type: 'text/plain'
});
const form = new FormData();
form.append('title', 'Release notes');
form.append('attachment', attachment);
await fetch('https://example.com/upload', {
method: 'POST',
body: form
});
Do not set content-type manually for FormData; the runtime creates the request header with the required boundary.
Observe headers and chunks with RequestTask
const task = wx.request({
url: 'https://api.example.com/agent/stream',
method: 'GET',
success(res) {
console.log('Final result:', res.data);
},
});
task.onHeadersReceived((headers) => {
console.log('Response headers:', headers);
});
task.onChunkReceived((chunk) => {
console.log('Chunk received:', chunk);
});
When to Use HTTPS
- Fetching initial page data
- Calling ordinary REST APIs
- Submitting one-off forms or commands
- Requesting one complete result and reading it with
json(),text(), orarrayBuffer() - Sending one HTTP request while consuming the response body incrementally
Streaming Consumption Notes
- Use
response.body.getReader()when you need incremental access to text or bytes. - Use
text(),json(), orarrayBuffer()when you only care about the final buffered result. - Once the body is locked to a reader, convenience methods such as
text()andjson()can no longer reuse that same body. - When text may cross chunk boundaries, using
TextDecoder.decode(value, { stream: true })is safer for incremental decoding.
HTTPS Recommendations
- Prefer modeling one business action as one clear HTTP request.
- If you only care about the final result,
response.json()orwx.request().successis usually the simplest choice. - If one request returns chunked content over time, prefer
fetchwithresponse.bodyfor incremental consumption. - Set clear timeout, cancellation, failure messaging, and retry strategies.
- For authenticated APIs, handle authentication consistently in request headers or session mechanisms.
When Not to Use HTTPS
- When you need long-lived one-way server push instead of a response triggered by a single request
- When bidirectional real-time communication is required between client and server
If you need continuous one-way server push, continue with Event Source. If you need bidirectional real-time communication, use WebSocket instead.
Read Next
- Event Source: Learn the typical usage pattern for one-way streaming pushes from the server.
- WebSocket: Learn how to design and manage bidirectional real-time long connections.
- WeChat Mini Program Compatible APIs: See the wx APIs supported by AIUI.
API Reference
Entry Points
AIUI currently provides two common entry points:
fetch(url, options?): Closer to Web standards and better suited for Promise-based code andResponse-style consumption.wx.request(options): Closer to the WeChat Mini Program compatible API style and better suited for callback-based code andRequestTask-style control.
fetch(input, options?)
fetch() sends an HTTP / HTTPS request and returns a Promise<Response>.
Parameters
input
The request address can be a string, URL, or Request. When a Request is passed, fields in options override the corresponding request settings.
const response = await fetch('https://example.com/data.json');
options.method
HTTP method. Defaults to GET.
await fetch('https://example.com/items', {
method: 'POST',
});
options.headers
Request headers object. The current implementation reads header values as strings.
await fetch('https://example.com/items', {
headers: {
Authorization: `Bearer ${token}`,
'content-type': 'application/json',
},
});
options.body
The request body accepts a string, Blob, FormData, URLSearchParams, ArrayBuffer, typed array, or ReadableStream.
await fetch('https://example.com/items', {
method: 'POST',
headers: {
'content-type': 'application/json',
},
body: JSON.stringify({
title: 'hello',
}),
});
options.timeout
Per-request timeout in milliseconds.
await fetch('https://example.com/items', {
timeout: 3000,
});
options.signal
An AbortSignal used to cancel the request.
const controller = new AbortController();
fetch('https://example.com/items', { signal: controller.signal });
controller.abort();
Request
new Request(input, options?)
Prepares a request from a URL string, URL, or another Request, with the request options above. Supplied options override the original request settings.
method
Read-only HTTP method, defaulting to GET. Packaged resources support GET/HEAD only.
url
Read-only request URL. Package-root and package-scoped file:/// URLs are local resources; remote endpoints require explicit HTTP/HTTPS URLs.
headers
Request Headers object for reading and updating headers before sending.
body
Read-only ReadableStream or null. Stream reads and convenience readers consume the same body; locking prevents other consumers until the lock is released, and consumed bytes cannot be reread.
bodyUsed
Read-only boolean indicating whether body consumption has started. A body can be locked before it is consumed; even while bodyUsed is false, another consumer cannot use a locked body.
signal
Read-only associated AbortSignal. Use the controller that supplied it to cancel a request.
redirect
Read-only configured redirect mode for the request.
clone()
Returns a new Request with an independently readable body. Clone before acquiring a reader or consuming the body; locked or consumed bodies throw TypeError.
text()
Returns Promise<string> and consumes the body as UTF-8 text. Reusing a locked or consumed body rejects with TypeError.
json()
Returns a Promise for the JSON value parsed from body text. Shares consumption state with all other readers; invalid JSON rejects.
arrayBuffer()
Returns Promise<ArrayBuffer> containing the body's bytes and consumes the body. An absent body produces an empty buffer.
blob()
Returns Promise<Blob> and consumes the body. The Blob type derives from the content-type header when present.
Blob, File, and FormData
new Blob(parts, options?)creates immutable binary data and supportsarrayBuffer(),bytes(),text(),stream(), andslice().new File(parts, name, options?)addsnameandlastModifiedtoBlobdata.new FormData()manages form fields withappend(),set(),get(),getAll(),has(),delete(),entries(),keys(),values(), andforEach().
Response
The Promise returned by fetch() resolves as soon as the response headers are available, rather than waiting for the full response body to finish downloading. This means:
- You can inspect metadata such as
statusandokfirst. - If the server returns chunked data, you can consume it incrementally through
response.body. - If you only care about the final result, you can use convenience methods such as
text(),json(), andarrayBuffer(). - When the response uses HTTP
Content-Encoding, body readers observe decoded body bytes rather than raw compressed transport bytes.
Common Fields
response.ok
true when the status code is in the 200-299 range.
response.status
Numeric HTTP status code, such as 200, 404, or 500.
response.statusText
HTTP status text. In the current implementation, 200 returns "OK" and other statuses are usually an empty string.
response.url
The URL associated with this response.
response.body
The response body as a ReadableStream. If the server returns data in chunks, use getReader() to read it incrementally instead of waiting for the full response to finish.
const response = await fetch('https://example.com/stream');
const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');
let buffer = '';
while (true) {
const { value, done } = await reader.read();
if (done) {
break;
}
buffer += decoder.decode(value, { stream: true });
}
buffer += decoder.decode();
console.log(buffer);
response.bodyUsed
Indicates whether response-body consumption has started. Locking and consumption differ: acquiring a reader can leave the body unused, but other readers still fail while it is locked. Once reading starts, bodyUsed is true.
Common Methods
response.clone()
Returns a new clone of the current response. The current implementation supports consuming the original response and the cloned response independently.
const response = await fetch('https://example.com/data.json');
const copy = response.clone();
console.log(await response.text());
console.log(await copy.text());
response.text()
Decodes the response body as text. It waits for the full response body to be read before returning the final text.
const response = await fetch('https://example.com/message.txt');
console.log(await response.text());
response.json()
Parses the response body as JSON. It reads the full response body before parsing.
const response = await fetch('https://example.com/data.json');
console.log(await response.json());
response.arrayBuffer()
Reads the response body as an ArrayBuffer, which is useful for binary content.
const response = await fetch('https://example.com/model.bin');
const buffer = await response.arrayBuffer();
console.log(buffer.byteLength);
response.blob()
Reads the response body as a Blob, which is useful for binary content that should retain its media type.
wx APIs
wx.request(options)
wx.request() provides a WeChat Mini Program compatible HTTPS request entry and is better suited for callback-based code or RequestTask-style control.
Parameters
options.url
Request URL.
options.method
HTTP method. Defaults to GET.
options.header
Request headers object.
wx.request({
url: 'https://example.com/items',
header: {
Authorization: `Bearer ${token}`,
},
});
options.data
Request data. The current implementation accepts:
StringArrayBuffer- plain objects
- form-like objects
When content-type contains application/x-www-form-urlencoded, objects are encoded as form data. Otherwise plain objects are typically serialized as JSON strings.
wx.request({
url: 'https://example.com/items',
method: 'POST',
header: {
'content-type': 'application/json',
},
data: {
title: 'hello',
},
});
options.body
Fallback string body that can be used when data is not provided.
options.timeout
Per-request timeout in milliseconds.
options.responseType
Response body mode. Defaults to text. When set to arraybuffer, res.data in the success callback is an ArrayBuffer.
options.dataType
Response parsing mode. Defaults to json. When set to json, the runtime attempts to parse the response before assigning it to res.data.
options.success
Success callback. The result object typically includes:
datastatusCodeheadercookieserrMsg
options.fail
Failure callback. It typically receives an object containing errMsg.
options.complete
Completion callback. It runs whether the request succeeds or fails.
RequestTask
wx.request(...) returns a RequestTask, which can be used to abort the request or observe earlier response events.
Methods
abort(): Aborts the current request.onHeadersReceived(callback)/offHeadersReceived(callback?): Adds or removes a listener for response headers.onChunkReceived(callback)/offChunkReceived(callback?): Adds or removes a listener for response body chunks.
Behavior Notes
onHeadersReceived()fires as soon as response headers arrive, before the request fully completes.onChunkReceived()fires repeatedly as new response body chunks arrive.- Even when chunk events are enabled,
success()andcomplete()still wait for the full response to finish.