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. The first section to look at is setting the userName and password into the headers. After that it is time to make the call. Once you have all the variables filled in all you have to do is wire a button to the Ajax call below and you will be able to make a call to create a basic role.
The route we will be using is https://api.connectionsonline.net/v4/basicroles, and the help for creating a basic role can be found in the documentation: Create a basic role help.
Before the call we must first set cors to be true and setup our basic role variable.
function CreateBasicRole() {
jQuery.support.cors = true;
var basicRole = {
IndividualID: $('#txtIndividualID').val(),
Name: $('#txtName').val(),
Rank: $('#txtRank').val(),
Description: $('#txtDescription').val(),
PercentTime: $('#txtPercentTime').val(),
};
The next step is to setup our 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);
},
In the next section we set the url to https://api.connectionsonline.net/v4/basicroles/ and make sure the type is 'POST'. We will set JSON.stringify and the content type to JSON so that we let the API know we are sending JSON and expect it to return JSON. When our call succeeds it will call the function WriteBasicRoleResponse and pass in the data. After which it will hide the #result div. The WriteBasicResponse function is described below. This will display our data, the error div is for any error messages that happen to be thrown. On a success this should be hidden so the user will not see a section for errors. The result section will take the "created at location" information from the response headers and put a direct link to the object in the result div. Finally the error section will write any errors it catches to the log and into the result div.
url: 'https://api.connectionsonline.net/v4/basicroles/',
type: 'POST',
data: JSON.stringify(basicRole),
contentType: "application/json;charset=utf-8",
processData: true,
success: function (data, status, xhr) {
WriteBasicRoleResponse(data);
$('#error').hide();
$('#result').html('<a href="' + xhr.getResponseHeader('Location') + '">' + xhr.getResponseHeader('Location') + '</a>').show();
},
error: function (jqXHR, textStatus, errorThrown) {
$('#result').hide
$('#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);
}
});
}
Once we put all those pieces together this is what the full Ajax call will look like.
function CreateBasicRole() {
jQuery.support.cors = true;
var basicRole = {
IndividualID: $('#txtIndividualID').val(),
Name: $('#txtName').val(),
Rank: $('#txtRank').val(),
Description: $('#txtDescription').val(),
PercentTime: $('#txtPercentTime').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/basicroles/',
type: 'POST',
data: JSON.stringify(basicRole),
contentType: "application/json;charset=utf-8",
processData: true,
success: function (data) {
WriteBasicRoleResponse(data);
$('#result').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);
}
});
}
The last function we need to get everything working is our WriteBasicRoleResponse function. This code takes the response and sets each variable into read-only text boxes. Of course you don't have to use text boxes. You can change this code to put the response anywhere you like. We will do that in another example.
function WriteBasicRoleResponse(basicRole) {
$('#txtBasicRoleIDResponse').val(basicRole.ID);
$('#txtIndividualIDResponse').val(basicRole.IndividualID);
$('#txtNameResponse').val(basicRole.Name);
$('#txtDescriptionResponse').val(basicRole.Description);
$('#txtRankResponse').val(basicRole.Rank);
$('#txtPercentTimeResponse').val(basicRole.PercentTime);
$('#txtCreatedResponse').val(basicRole.Created);
$('#txtCreatedByResponse').val(basicRole.CreatedBy);
$('#txtUpdatedResponse').val(basicRole.Updated);
$('#txtUpdatedByResponse').val(basicRole.UpdatedBy);
}