Network APIs

request

Network request for a Mini Program.

Overview

my.request initiates a network request from a Mini Program. The API supports GET and POST methods and returns a RequestTask object that can be used to abort the request.

Notes

Configure the domain name whitelist at first under Mini Program > Configuration > Server Domain Whitelist. The Mini Program can only communicate with the domain names in the whitelist during the API calls: my.request (send HTTP request), my.uploadFile (upload file), and my.downloadFile (download file).
During the Mini Program development, preview and debugging stages, you can select whether to ignore the httpRequest domain name validity check under Details > Domain name information. If yes, the domain name validity will not be checked in the simulator, preview and debug versions. Before the Mini Program goes online, you must maintain the domain names in the whitelist, otherwise, the domain names cannot be effective in the official release.

Important:my.request request header is {'content-type': 'application/json'} by default, instead of {'content-type': 'application/x-www-form-urlencoded'}.

Sample Code

my.request({
  url: 'https://httpbin.org/post',
  method: 'POST',
  data: {
    from: 'Mini Program',
    production: 'JSAPI',
  },
  dataType: 'json',
  success: function(res) {
    my.alert({content: 'success'});
  },
  fail: function(res) {
    my.alert({content: 'fail'});
  },
  complete: function(res) {
    my.hideLoading();
    my.alert({content: 'complete'});
  }
});

const task = my.request({url: 'https://httpbin.org/post'});
task.abort();

Parameters

Property	Type	Required	Description
`url`	`String`	Yes	Target server url.
`headers`	`Object`	No	Set the request HTTP header. The default value is `{'content-type': 'application/json'}`.
`method`	`String`	No	The default value is GET. Both GET and POST are supported.
`data`	`Object`	No	Request parameter.
`timeout`	`Number`	No	Timeout period in ms. The default value is 30000.
`dataType`	`String`	No	Expected format of the returned data. The following formats are supported: • `json` • `text` • `base64` The default format is JSON. If an exception occurs, it may not be JSON in the callback.
`success`	`Function`	No	The callback function for a successful API call.
`fail`	`Function`	No	The callback function for a failed API call.
`complete`	`Function`	No	The callback function used when the API call is completed. This function is always executed no matter the call succeeds or fails.

Data Parameter Description

Data transferred to the server is eventually expressed in String. If the type is not String, the data will be converted into String. Conversion rules are:

If the method is GET, the data will be converted into query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...
If the method is POST and the headers['content-type'] is application/json, the data will be JSON serialized.
If the method is POST and the headers['content-type'] is application/x-www-form-urlencoded, the data will be converted into query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...

Success Callback Function

The type of the incoming parameter is Object with the following attributes:

Property	Type	Description
`data`	`String`	Response data. The format depends on the value of `dataType` in the request.
`status`	`Number`	Response code.
`headers`	`Object`	Response header.

Error Code

Error	Description
`2`	Incorrect parameter. Check whether the URL is in HTTPS format and all parameters are correct.
`4`	Not authorized to call the interface. The error might result from the following: • The server domain is not configured. In this case, configure the domain whitelist under `Mini Program > Configuration > Server Domain Whitelist`. The mini program can only communicate with the domain names in the whitelist when calling the `my.request` and `my.uploadFile` APIs. If the server domain whitelist is updated, the whitelist comes effective only when a new version of the mini program is published. • Errors occur with your account and you cannot login to the mini program editor. In this case, when you debug in the Mini Program studio, select `ignore HttpRequest domain name validity check` or `ignore Webview domain name validity check` under `Details > Domain name information`, and then preview the debugging request. Check whether the HTTP request domain name is incorrect.
`12`	Network error.
`13`	Timeout.
`14`	Decoding failure.
`19`	HTTP error.
`20`	Request stopped/service end traffic limit.

Note:

The error code of 14 might be returned in the following cases:

When the value of dataType is json, the Mini Program framework firstly perform the JSON.parse operation on the returned results. If the parsing fails, the error code of 14 is returned.
When the value of dataType is text and the returned content has a bad format, the error code of 14 is returned.

To solve the error, check whether the dataType setting is incorrect firstly.

Return Value

RequestTask

Network request task object.

Method:

RequestTask.abort()

Note:

If Not authorized to call the interface is returned, configure the domain whitelist under Mini Program > Configuration > Server Domain Whitelist in the mini program platform.

Usage Notes

Domain whitelist must be configured before making requests
Default content-type is application/json, not application/x-www-form-urlencoded
Default timeout is 30000ms (30 seconds)
The request can be aborted using the returned RequestTask object
Both GET and POST methods are supported