Frontend {menu:}
EXC | DEV |
DocumentationHTTP
This topic applies to the Front-End framework.Use the HTTP object to make a request using http/https, like calling an API or loading resources from a server.
Dependencies: CORE.
## Making a basic GET or POST request ## {#makerequest}
Use the functions
http.get()
and
http.post()
to initiate a HTTP request.
var request = http.get(url);
var request = http.get(url, data);
var request = http.get(url, data, callback);
var request = http.get(url, callback);
The only required argument is either a
url
or a plain object with options. (See "Setting more options".)
Arguments | Description |
url | String with a valid URL. A url parameter may be replaced with the options argument. |
options | A plain object with configuration options. |
data | Optional A URL encoded string or a plain object (key value pairs) |
callback | Optional A function called when the request is completed. Is called for both, success and errors. See "Using the callback". |
Setting more options
You can pass a plain object to the functions
http.get()
and
http.post()
to control and configure various options of a request.
This plain object replaces our
url
parameter and as such it must include the property
url
in your options object.
var options = {
url: "http://example.com/",
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
}
}
var request = http.get(options);
var request = http.get(options, data);
var request = http.get(options, data, callback);
var request = http.get(options, callback);
The following options are available.
Option | Description |
url | Required String with a valid URL. |
headers | A plain object with headers. "POST" request set the Content-Type header to application/x-www-form-urlencoded by default. |
opRunJS | A boolean that indicates if javascript code received with the content-type of application/javascript is executed automatically. Default is true. See "Javascript Payloads". |
timeout | The number of milliseconds a request can take before automatically being terminated. The default value is 0, which means there is no timeout. |
mimeType | Overrides the MIME type returned by the server. |
withCredentials | A Boolean that indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. Setting withCredentials has no effect on same-site requests. (Source MDN) |
## Handling the response ## {#handleresp}
The HTTP request provides three ways to handle a response, using events, using a promise interface or by a more traditional callback.
## Using events ## {#useevents}
var request = http.post(url, data);
request.on( "done", function(response){
console.log("Response Type: %s", response.type );
console.log(response.data);
//example reading json data
console.log("Employee id= " + response.data.empID);
});
request.on("error", function(response){
console.log("Request failed...");
console.log("Error: " + response.lastError);
});
With the HTTP request you register a callback for one of the events published by the request.
The event
done
is triggered from a successful request. The handler receives a
response
object as argument. We use the
response
object to get our data and other useful information.
The event
error
is triggered for errors and also receives a
response
object. To check which error occurred we use the
response.lastError
property.
## Using a promise ## {#usepromise}
In addition of using events the HTTP request provides a
PROMISE interface with a
then()
and
catch()
method.
var params = {
name: "Jose",
code: 201,
};
var url = "http://localhost/echo.php";
http.get(url, params).then(function(response){
console.log(response);
});
## Using a callback ## {#usecallback}
When you specify a callback function in your
http.get()
or
http.post()
the callback will be executed when the request is completed. This callback is called regardless if the request was successful or had an error.
var request = http.post(url, data, function(response){
if(response.lastError !=0 ){
console.log("request failed...");
return;
}
console.log("Response Type: %s", response.type );
console.log(response.data);
//example reading json data
console.log("Employee id= " + response.data.empID);
});
Just like events the callback receives a
response
object as argument.
In your callback you can check the property
response.lastError
.
## Response Object ## {#response}
Properties of a response object:
Property | Description |
data | The actual payload. It may be undefined , an empty string , a string , an object , or an array . |
type | A string indicating the type of payload received. A "json" type means that your data is an object or array . A "blob" type means you got text or binary data specific to your request. A type of "js" means that the payload is actual javascript code. |
status | An integer with the HTTP response status. |
url | A string of the final URL obtained after any redirects. |
lastError | An integer with an error code. Its value is zero for no errors. |
## JSON Payloads ## {#jsonpayload}
A request may send JSON encoded data in the body of a response with the
content-type
of
text/json
or
application/json
.
The JSON payload will be converted to a JS object or array.
An example in PHP will be:
<?php
$data_out = json_encode($data);
header("Content-Type: application/json");
print $data_out;
exit;
?>
## JavaScript Payloads ## {#jspayload}
A response may contain plain javascript code to be executed by sending the
content-type
application/javascript
in this case the
response.type
is set to
js
.
The code is executed automatically by default. Set the option
opRunJS
to disable automatic execution.
The code executed exposed the plain object
ajaxResponse
which can be used to pass data back to the promise in the
response.data
property. For example:
ajaxResponse.empName = "Jose";
If the option
opRunJS
is false, then
response.data
has the actual javascript code.
Javascript syntax errors will cause the request to fail.
## Receiving arbitrary data ## {#arbitrarydata}
Arbitrary data have a
content-type
set to a value other than the ones expected above. The
response.type
is set to
blob
and the actual string data is in
response.data
.
## JSON Stream ## {#jsonstream}
A JSON Steam allows an API to send a large set or continuous JSON data over a single request.
EXC supports
Record separator-delimited JSON as a JSON Stream format. See
JSON Streaming in Wikipedia.
When a
content-type
header with
application/json-seq
is received EXC will poll the connection to process JSON records.
Each time JSON records are received a
"jsonEntries"
event will be triggered.
request.on("jsonEntries", function(entries, response){
console.log(response);
console.log("Response Type: %s", response.type );
console.log("entries %o", entries); //array or records...
for(var i in entries){
var entry = entries[i];
}
});
The
entries
argument of the event handler is an array of the JSON objects received.
NOTE: The
"done"
event will be executed when the streaming stops. The
response.data
property will be an empty object for a JSON Stream.
## Canceling a request ## {#cancel}
Use the function
request.abort()
to cancel a request. An "error" event will be triggered with the
response.lastError
set to
503
.
HTTP Error Codes
Code | Description |
501 | Request time out. |
502 | An unspecified XHR error. |
503 | Request aborted or interrupted. |
504 | The HTTP status of the response is not a 200. |
510 | Access forbidden, HTTP Status 403. |
511 | The resource was not found, HTTP Status 404. |
520 | Invalid JSON, unable to parse JSON. |
521 | Invalid javascript code, syntax error or runtime error. |