Adding own default headers and per-request headers is now possible, extended readme

Author: DigitalFlow

README.md

@@ -107,3 +107,39 @@ WebApiClient.Delete(request)
         // Handle error
     });
 ```
+
+## Headers
+
+### Header Format
+Headers are represented as objects containing a key and a value property:
+
+```JavaScript
+var header = { key: "headerKey", value: "headerValue" };
+```
+
+### Default Headers
+By default there is a defined set of default headers, that will be sent with each request.
+You can however manipulate the default headers by accessing the WebApiClient.DefaultHeaders array property.
+
+### Request Headers
+You can also attach headers per request, all request parameters have a headers property, that can be used for passing per-request headers.
+
+This could look something like this:
+``` JavaScript
+// Parameters for create request
+var request = {
+    entityName: "account", 
+    entity: {name: "Adventure Works"},
+    headers: [ { key: "headerKey", value: "headerValue" }]
+};
+
+Note: Currently your request headers are simply added after the default headers. Watch out for interferences.
+```
+
+### API Version
+The default API version is 8.0.
+You can however change it to 8.1 if needed by using 
+
+```JavaScript
+WebApiClient.SetApiVersion("8.1");
+```

src/js/WebApiClient.js

@@ -25,7 +25,7 @@
 (function (WebApiClient, undefined) {
     var Promise = require("bluebird");
 
-    var apiVersion = "8.0";
+    var ApiVersion = "8.0";
 
     function GetCrmContext() {
         if (typeof (GetGlobalContext) !== "undefined") {
@@ -53,8 +53,12 @@
         return id.replace("{", "").replace("}", "");
     }
 
+    WebApiClient.GetApiVersion = function() {
+        return ApiVersion;
+    };
+    
     WebApiClient.SetApiVersion = function(version) {
-        apiVersion = version;
+        ApiVersion = version;
     };
 
     WebApiClient.GetSetName = function (entityName) {
@@ -71,8 +75,50 @@
         }
     };
 
+    var DefaultHeaders = [
+        { key: "Accept", value: "application/json" },
+        { key: "OData-Version", value: "4.0" },
+        { key: "OData-MaxVersion", value: "4.0" },
+        // Prevent caching since it sometimes sends old data as unmodified
+        { key: "If-None-Match", value: null }
+    ];
+    
+    WebApiClient.GetDefaultHeaders = function() {
+        return DefaultHeaders;
+    };
+    
+    function VerifyHeader(header) {
+        if (!header.key || typeof(header.value) === "undefined") {
+            throw "Each request header needs a key and a value!";
+        }
+    }
+    
+    WebApiClient.AppendToDefaultHeaders = function () {
+        if (!arguments) {
+            return;
+        }
+        
+        for(var i = 0; i < arguments.length; i++) {
+            var argument = arguments[i];
+            
+            DefaultHeaders.push(arguments[i]);
+        }
+    };
+    
+    function AppendHeaders(xhr, headers) {
+        if (headers) {
+            for (var i = 0; i < headers.length; i++) {
+                var header = headers[i];
+                
+                VerifyHeader(header);
+                
+                xhr.setRequestHeader(header.key, header.value);
+            }
+        }
+    }
+    
     // Private function
-    function SendRequest (method, url, payload) {
+    function SendRequest (method, url, payload, requestHeaders) {
         var xhr = new XMLHttpRequest();
 
         var promise = new Promise(function(resolve, reject) {
@@ -104,20 +150,16 @@
 
         xhr.open(method, url, true);
 
-        xhr.setRequestHeader("Accept", "application/json");
-        xhr.setRequestHeader("OData-Version", "4.0");
-        xhr.setRequestHeader("OData-MaxVersion", "4.0");
-        
-        // Prevent caching since it sometimes sends old data as unmodified
-        xhr.setRequestHeader("If-None-Match", null);
+        AppendHeaders(xhr, WebApiClient.DefaultHeaders);
+        AppendHeaders(xhr, requestHeaders);
 
         xhr.send(JSON.stringify(payload));
 
         return promise;
     }
 
     WebApiClient.GetApiUrl = function() {
-        return GetClientUrl() + "/api/data/v" + apiVersion + "/";
+        return GetClientUrl() + "/api/data/v" + ApiVersion + "/";
     };
 
     WebApiClient.Create = function(parameters) {
@@ -129,7 +171,7 @@
 
         var url = WebApiClient.GetApiUrl() + WebApiClient.GetSetName(params.entityName);
 
-        return SendRequest("POST", url, params.entity);
+        return SendRequest("POST", url, params.entity, params.headers);
     };
 
     WebApiClient.Retrieve = function(parameters) {
@@ -147,7 +189,7 @@
 
         url += params.queryParams;
 
-        return SendRequest("GET", url);
+        return SendRequest("GET", url, null, params.headers);
     };
 
     WebApiClient.Update = function(parameters) {
@@ -159,7 +201,7 @@
 
         var url = WebApiClient.GetApiUrl() + WebApiClient.GetSetName(params.entityName) + "(" + RemoveIdBrackets(params.entityId) + ")";
 
-        return SendRequest("PATCH", url, params.entity);
+        return SendRequest("PATCH", url, params.entity, params.headers);
     };
 
     WebApiClient.Delete = function(parameters) {   
@@ -171,6 +213,6 @@
 
         var url = WebApiClient.GetApiUrl() + WebApiClient.GetSetName(params.entityName) + "(" + RemoveIdBrackets(params.entityId) + ")";
 
-        return SendRequest("DELETE", url);
+        return SendRequest("DELETE", url, null, params.headers);
     };
 } (window.WebApiClient = window.WebApiClient || {}));

src/spec/WebApiClientSpec.js

@@ -222,4 +222,31 @@ describe("WebApiClient", function() {
             xhr.respond();
         });
     });
+    
+    describe("Headers", function() {
+        it("should set default headers", function(){
+            expect(WebApiClient.GetDefaultHeaders()).toBeDefined();
+        });
+        
+        it("should allow to add own default headers", function(){
+            var testHeader = {key: "newHeader", value: "newValue"};
+            WebApiClient.AppendToDefaultHeaders (testHeader);
+            
+            var defaultHeaders = WebApiClient.GetDefaultHeaders();
+            
+            expect(defaultHeaders[defaultHeaders.length - 1]).toEqual(testHeader);
+        });
+    });
+    
+    describe("API Version", function() {
+        it("should default to 8.0", function() {
+            expect(WebApiClient.GetApiVersion()).toEqual("8.0");
+        }); 
+        
+        it("should be editable", function() {
+            WebApiClient.SetApiVersion("8.1")
+            
+            expect(WebApiClient.GetApiVersion()).toEqual("8.1");
+        }); 
+    });
 });