Something to keep in mind while programming to this API is anything you can do with Connections Online you can do with the API. However your access to data does not change so you will not be able to gain access to anything you currently cannot access using the main application.
During this example we will be using Ajax to make a call to the database. We will make 2 different calls, the first will be a GET. This will read the metric we are about to update. Next we will use a PUT call to update the metric. Doing the GET first is not always necessary. However, any parameters you leave out of the PUT call will default to null. So for this example we will get the item change what we want and upload the entire item back to the server. The fields marked as "Required" in the documentation are the ones you will need to send in on update. If you send in less than these fields it will still work, however it will null all the values in the missing fields.
The route we will be using is https://api.connectionsonline.net/v4/metrics, and the help for metrics can be found in the documentation here for a GET and here for a PUT. If you want to skip to the completed product you can visit it here. It is a simple page that takes UserName Password a metric ID and allows you to update it.
For authentication we will use basic authentication with the username and password base 64 encoded. All of our communications will be going over SSL so they will stay safe and secure. In the code below we are getting the UserName and Password from textboxes on the HTML page, base64 Encoding them and then setting them in the Authorization header.
beforeSend: function (request) {
var restAuthHeader = btoa($('#txtUserName').val() + ':' + $('#txtPassword').val());
request.withCredentials = true;
request.setRequestHeader("Authorization", "Basic " + restAuthHeader);
},
Next we will look at the call to the API using Ajax. This is just setting the parameters to the values we expect. In this instance we are expecting to return json, however we could have changed this to xml or csv. On a success it calls the function "LoadMetric" passing in the data it received from the API.
url: 'https://api.connectionsonline.net/v4/metrics/' + id,
type: 'GET',
dataType: 'json',
: function (data) {
LoadMetric(data);
$('#error').hide();
},
error: function (jqXHR, textStatus, errorThrown) {
$('#error').html('<p>status code: ' + jqXHR.status + '</p><p>errorThrown: ' + errorThrown + '</p>').show();
console.log('textStatus:');
console.log(textStatus);
console.log('errorThrown:');
console.log(errorThrown);
}
});
}
Once we put all of these pieces together this is what your Ajax call should look like.
function GetMetric() {
jQuery.support.cors = true;
var id = $('#txtMetricID').val();
$.ajax({
beforeSend: function (request) {
var restAuthHeader = btoa($('#txtUserName').val() + ':' + $('#txtPassword').val());
request.withCredentials = true;
request.setRequestHeader("Authorization", "Basic " + restAuthHeader);
},
url: 'https://api.connectionsonline.net/v4/metrics/' + id,
type: 'GET',
dataType: 'json',
success: function (data) {
LoadMetric(data);
$('#error').hide();
},
error: function (jqXHR, textStatus, errorThrown) {
$('#error').html('<p>status code: ' + jqXHR.status + '</p><p>errorThrown: ' + errorThrown + '</p>').show();
console.log('textStatus:');
console.log(textStatus);
console.log('errorThrown:');
console.log(errorThrown);
}
});
}
Next we will take a quick look at two code samples. One for Load Metric that we just saw being called and the other WriteResponse which will be called after an update. All these methods do is take the data and put it into text boxes.
function LoadMetric(metric) {
$('#lblMetricID').val(metric.ID);
$('#txtParentID').val(metric.ParentID);
$('#txtRank').val(metric.Rank);
$('#txtName').val(metric.Name);
$('#txtDescription').val(metric.Description);
$('#txtFormat').val(metric.Format);
$('#txtColor').val(metric.Color);
$('#txtTColor1').val(metric.TColor1);
$('#txtTColor2').val(metric.TColor2);
$('#txtTColor3').val(metric.TColor3);
$('#txtTColor4').val(metric.TColor4);
$('#txtThreshold1').val(metric.Threshold1);
$('#txtThreshold2').val(metric.Threshold2);
$('#txtThreshold3').val(metric.Threshold3);
$('#selColorByValue').val(metric.ColorByValue);
$('#selIs8020').val(metric.is8020);
}
function WriteResponse(metric) {
$('#lblMetricIDResponse').val(metric.ID);
$('#txtParentIDResponse').val(metric.ParentID);
$('#txtRankResponse').val(metric.Rank);
$('#txtNameResponse').val(metric.Name);
$('#txtDescriptionResponse').val(metric.Description);
$('#txtFormatResponse').val(metric.Format);
$('#txtColorResponse').val(metric.Color);
$('#txtTColor1Response').val(metric.TColor1);
$('#txtTColor2Response').val(metric.TColor2);
$('#txtTColor3Response').val(metric.TColor3);
$('#txtTColor4Response').val(metric.TColor4);
$('#txtThreshold1Response').val(metric.Threshold1);
$('#txtThreshold2Response').val(metric.Threshold2);
$('#txtThreshold3Response').val(metric.Threshold3);
$('#txtColorByValueResponse').val(metric.ColorByValue);
$('#txtIs8020Response').val(metric.is8020);
}
For the update the first thing we must do is setup the object we will send. We do this by loading the values from the text boxes into a metric variable. We do this right after setting up cors and before our Ajax call.
After that we send in the UserName/Password. We need to be careful that we have the type set as 'PUT' and the content type set to what we want, in this case JSON.
function UpdateMetric() {
jQuery.support.cors = true;
var metric = {
ID: $('#lblMetricID').val(),
ParentID: $('#txtParentID').val(),
Rank: $('#txtRank').val(),
Name: $('#txtName').val(),
Description: $('#txtDescription').val(),
Format: $('#txtFormat').val(),
Color: $('#txtColor').val(),
TColor1: $('#txtTColor1').val(),
TColor2: $('#txtTColor2').val(),
TColor3: $('#txtTColor3').val(),
TColor4: $('#txtTColor4').val(),
Threshold1: $('#txtThreshold1').val(),
Threshold2: $('#txtThreshold2').val(),
Threshold3: $('#txtThreshold3').val(),
ColorByValue: $('#selColorByValue').val(),
Is8020: $('#selIs8020').val()
};
$.ajax({
beforeSend: function (request) {
var restAuthHeader = btoa($('#txtUserName').val() + ':' + $('#txtPassword').val());
request.withCredentials = true;
request.setRequestHeader("Authorization", "Basic " + restAuthHeader);
},
url: 'https://api.connectionsonline.net/v4/metrics/',
type: 'PUT',
data: JSON.stringify(metric),
contentType: "application/json;charset=utf-8",
success: function (data) {
WriteResponse(data);
$('#error').hide();
},
error: function (jqXHR, textStatus, errorThrown) {
$('#error').html('<p>status code: ' + jqXHR.status + '</p><p>errorThrown: ' + errorThrown + '</p>').show();
console.log('jqXHR:');
console.log(jqXHR);
console.log('textStatus:');
console.log(textStatus);
console.log('errorThrown:');
console.log(errorThrown);
}
});
}