Awesome
http.gml v2.0
A complete rewrite of http.gml. It's much nicer now.
Documentation is now located at docs.sidorakh.net/http.gml
Trust me, it's better that way
The old documentation is below for posterity
http(url, method, body, options, callback, [error], [progress])
A wrapper for http_request
, returns the HTTP request ID. The callbacks passed in are called at appropriate times.
Parameter | Type | Description |
---|---|---|
url | String | A valid URL |
method | String | A valid HTTP Request Method |
body | String/FormData | An HTTP request body, either a string or FormData |
options | Struct<HTTPOptions> | A struct setting various options in the request (further docs below) |
callback | function | A function to be called if the HTTP request succeeds |
error | function | (Optional) A function to be called if the HTTP request fails |
progress | function | (Optional) A function to be called when the HTTP request is still in progress |
options <HTTPOptions>
Property | Type | Description |
---|---|---|
headers | Real (ds_map) | A ds_map index of headers to be sent with the HTTP reequest. If not provided, a map is created |
keep_header_map | Boolean | Whether or not to keep the header map (useful if the headers are reused and don't need to change often) |
get_file | Boolean | Whether or not to store the response in a buffer , which can be accessed in options.buffer in the progress callback, and result in the error and success callbacks) |
filename | String | The file to output to when using http_get_file |
keep_form_data | Boolean | Whether or not to clean up/destroy the FormData object included in a HTTP request. Ignored if no FormData object is passed in as body |
buffer | Real (Buffer) | A buffer containing the HTTP response if the get_file flag is set |
keep_buffer | Boolean | Whether or not to automatically delete the buffer generated by the get_file flag (default: false ) |
response_headers | Real (ds_map) | Response headers for the request, if available |
callback(http_status, result, [options])
A function to be called when the HTTP request is successful
Parameter | Type | Description |
---|---|---|
http_status | Real | HTTP status code |
result | String | Real |
options | Struct<HTTPOptions> | The options object passed into the http function (optional) |
error(http_status, result, [options])
A function to be called when the HTTP request is unsuccessful
Parameter | Type | Description |
---|---|---|
http_status | Real | HTTP status code |
result | String | Real |
options | Struct<HTTPOptions> | The options object passed into the http function (optional) |
progress(content_length, size_downloaded, [options])
A function that is called when an HTTP request is still in progress (and has not completed or failed)
Parameter | Type | Description |
---|---|---|
content_length | Real | Total response size |
size_dwnloaded | String | Data downloaded |
options | Struct<HTTPOptions> | The options object passed into the http function (optional) |
FormData
A struct that implements FormData as best I can to the spec set out in rfc2045.
add_file(name, file, options)
Adds a file field to the FormData object
Parameter | Type | Description |
---|---|---|
name | String | Field name |
file | String | Path to file to load into FormData |
options | Struct<FormDataOptions> | Options related to file |
add_data(name, data)
Adds a data field to the FormData object
Parameter | Type | Description |
---|---|---|
name | String | Field name |
data | String | Field Data |
form_body
Returns the multipart/form-data
encoded body and the boundary, ready for use in the HTTP
function
Returns: [Buffer, String]
cleanup
Cleans up any buffers created and stored in the FormData object that were not flagged with keep_buffer
, except the results of the form_body
function
options<FormDataOptions>
Property | Type | Description |
---|---|---|
file_is_buffer | Boolean | Whether or not the File passed in to add_file is a Buffer instead of a file/path |
keep_buffer | Boolean | When using file_is_buffer , this controls whether or not the buffer is kept after the FormData object runs its cleanup() function |
filename | String | Filename to use for the uploaded file (in the form field). If blank, will use the filename in the file argument, or the string "unknown" if a buffer was specified |
mimetype | String | The mimetype to mark the file as. This is sniffed from the filename if there's a filetype registered with the IANA in the get_mime_from_extension() function |
Example Usage
Basic GET request
// Using the amazing yes/no API - https://yesno.wtf
http("https://yesno.wtf/api","GET","",{},function(status,result){
result = json_parse(result);
show_message(result.answer);
})
Uploading a file (multipart/form-data)
var form = new FormData();
form.add_file("file","codes.json");
form.add_data("foo","bar");
var headers = ds_map_create();
headers[? "X-App-Id"] = "ABC123"
http("https://enn3xyub5vujm.x.pipedream.net/", "POST", form, {headers:headers}, function(http_status,result){
show_message(result);
},function(http_status,result){
show_message("Error - " + result);
});
Downloading a photo of a cat
http("https://i.imgur.com/R42xZ1p.jpg","GET","",{get_file:true},
function(status,result){
buffer_save(result,"out.jpg");
// We have a cat, maaaaan!
}
);