owp.http

OpenWebProject HTTP

HTTP client for JavaScript

HTTP is a simple and lightweight wrapper for the browsers native XMLHttpRequest functionality.
The purpose of this utility is to easiliy enable HTTP request without relying on a large framework. No matter if you have a simple standard JS app, uses jQuery or react framework you can make use of HTTP request in the same way.

Installation and use

npm install owp.http --save

import HTTP from "owp.http";

Static requests

HTTP.useOptions(options);
const promise = HTTP.get("http://www.mysite.com/rest/data", options);
const promise = HTTP.delete("http://www.mysite.com/rest/data", options);
const promise = HTTP.head("http://www.mysite.com/rest/data", options);
const promise = HTTP.post("http://www.mysite.com/rest/data", options);
const promise = HTTP.put("http://www.mysite.com/rest/data", options);
const promise = HTTP.patch("http://www.mysite.com/rest/data", options);
const promise = HTTP.jsonp("http://www.mysite.com/rest/data", options);

Instance requests

HTTP.useOptions(options);
const http = new HTTP("http://www.mysite.com/rest", options);
const promise = http.get("data", options);
const promise = http.delete("data", options);
const promise = http.head("data", options);
const promise = http.post("data", options);
const promise = http.put("data", options);
const promise = http.patch("data", options);
const promise = http.jsonp("data", options);

Options

Name	Description
headers	Headers
params	Query parameters
data	Data payload
json	JSON data payload
fullResponse	Set to true to get full response
contentType	Media type(MIME) for data payload
responseType	Type for response data
cache	Set to true to cache responses
stateChangeInterceptor	State change interceptor callback
requestInterceptor	Request interceptor callback
responseInterceptor	Response interceptor callback
download	Set to true to download response data
filename	Filename for downloaded file

Options inheritence

• Add options to the class with useOptions(options)
  • Inherits NO options
• Add options to the static request HTTP.get("URL", options)
  • Inherits CLASS options
• Add options to the instance new HTTP("URL", options)
  • Inherits CLASS options
• Add options to the instance request http.get("PATH", options)
  • Inherits INSTANCE options

Path parameters

const id = "Fo%Bar";

//Static request. All paths string after the first(base) one is uri encoded.
const promise = HTTP.get("http://www.mysite.com/rest/data", id, "subpath");

//Instance constructor. All paths string after the first(base) one is uri encoded.
const http = new HTTP("http://www.mysite.com", "rest");
//Instance request. All path string are uri encoded.
const promise = http.get("data", id, "subpath");
//Instance request at base path.
const promise = http.get();

Headers and query parameters

//Headers. Flat object(key/value map)
const headers = { Origin: "http://www.mysite.com" };

//Query parameters. Object(key/value map) which supports multiple values per key.
//?id=123&field=name&field=value
const params = { id: "123", field: ["name", "value"] };

//Can be used for static requests.
const promise = HTTP.get("http://www.mysite.com/rest/data", { headers: headers, params: params });

//Can be given to the constructor and passed to each request.
const http = new HTTP("http://www.mysite.com/rest", { headers: headers, params: params });

//Can be defined for single request.
const promise = http.get("data", { headers: headers, params: params });

Payload

Payload parameters are the same for post/put/patch.

//Data with specified content type.
const promise = http.post({ data: "myData", contentType: "text/plain" });
//Data with undefined content type. String/boolean/number defaults to "text/plain".
const promise = http.post({ data: "myData" });
//Unspecified objects are converted to urlencoded query string a=1&b=2 with content type: "application/x-www-form-urlencoded".
const promise = http.post({ data: { a: 1, b: 2 } });
//Json object. Object is stringified and content type is "application/json".
const promise = http.post({ json: { a: 1, b: 2 } });

Response

Resolved promise returns payload.

http.get()
    .then(function (response) {
        //Response from server if promise resolved(request succeeded).
    })
    .catch(function (error) {
        //Full response object if promise rejected(request failed). Se  below for description of full response.
    });

Full response

Get a full response in both promise resolve and reject.

http.get({ fullResponse: true })
    .then(function(response) {
        //Full response returned.
    });

//Full response format.
{
    ok: true,
    url: "http://www.mysite.com/rest/data?id=123",
    status: 200,
    statusText: "OK",
    text: "{ value: 5 }",
    //Data is the same value that is returned in a simple(non full) response.
    data: { value: 5 },
    //Object with headers
    headers: { }
}

Response type

Specify response type. Can be used to request binary data

http.get({ responseType: "blob" }).then(function (blob) {
    //Blob containing binary data
});

Cache

Enable cache. Matches method+url and caches response.

http.get({ cache: true }).then(function (cachedResponse) {
    //Response is fetched from cache.
});

State change interceptor

Callback to trigger on every state change on the underlying XMLHttp​Request​.
0 UNSENT - Client has been created. open() not called yet.
1 OPENED - open() has been called.
2 HEADERS_RECEIVED - send() has been called, and headers and status are available.
3 LOADING - Downloading; responseText holds partial data.
4 DONE - The operation is complete.

stateChangeInterceptor: function (readyState) {
    switch (readyState) {
        //readyState = [0, 4]
    }
};

Request interceptor

Callback to format/update request. Useful for updating auth credentials.

requestInterceptor: function(request: object) {
    //Update auth credentials
    request.headers.Authorization = "...";
    //Return updated request
    return request;
    //Or return Promise.
    return Promise.resolve(request);
    //Returning rejected promise rejects the entire http request.
    return Promise.reject("Error");
}

Response interceptor

Callback to format/update response. Useful for logging errors.

responseInterceptor: function(response: object) {
    //Change response
    if (response.data === null) {
        response.data = "No Data, but ok";
    }
    //Log errors
    if (!response.ok) {
        console.error(response.statusText);
    }
    //Return updated response.
    return response;
    //Or return Promise.
    return Promise.resolve(response);
    //Returning rejected promise rejects the entire http request.
    return Promise.reject("Error");
}