API Request
Making an API request requires no special framework. The basics for the request require:
- Reference the JavaScript library.
- Create the API request object and fill parameter
- If the API is marked as secure, Authenticate must be set to 'true'
- Make the synchronous call OR specify the callback functions (success, failure)
Secure API
Authentication is used via the implementation of the AdvantageSecureContentControllerHandler. This is a messaging handler that needs to be registered when you register the routing for the API in the Global.asax.
Using secure methods requires you to return a successful 'AdvantageAuthResponse' from the method "AuthenticateRequest" implemented in the handler. You must also set the Authenticate = true for the client API
Enumerations
For advanced calls where you wish to limit, filter or sort results there are parameters you may set. These are utilize the following enumerations.
- Sort Direction - > advDirection = Object.freeze({ Asc: 'asc', Desc: 'desc' })
- Data Type -> advDataType = Object.freeze({ String: 'string', Date: 'date', Boolean: 'boolean', Decimal: 'decimal', Integer: 'integer', UniqueIdentifier: 'uniqueidentifier' })
- Comparison -> advCompare = Object.freeze({ Equals: 'equals', NotEquals: 'notequals', Like: 'like', NotLike: 'notlike', GreaterThan: 'greaterthan', GreaterOrEquals: 'greaterorequals', LessThan: 'lessthan', LessOrEquals: 'lessorequals', All: 'all' })
Filtering/Sorting
- Index (optional index defined on the object) {"Key":"indexname","DataType":"index data type","Comparison":"comparitor","Value":"value to compare"}
- AddFilter (optional array of 'where' criteria) [{"Key":"field name","DataType":"filter data type","Comparison":"comparitor","Value":"value to compare"}]
- AddSort (optional array of sorting criteria) [{"field name","direction"}] FieldList (optional array of fields to populate) [{"field name"}] MaxRecords (optional maximum records to return '0' is all) SkipRecords (optional records to skip '0' is none)
- MaxRecords (optional maximum records to return '0' is all)
- SkipRecords (optional records to skip '0' is none)
Return Value
Return values for the API are standardized in the following Json Object
- Data - > Array of items
- Error -> Error message (nullable)
- ResponseCode -> 200, 403, 404, 500
Example
Copy
|
|
|---|---|
<!DOCTYPE html>
<html>
<head runat="server">
<title>API Field List</title>
<style>
th, td {padding: 15px; vertical-align: top;}
table {margin: 0 auto; border-collapse: separate; border-spacing: 5px; border-collapse: collapse; border-spacing: 0;}
</style>
</head>
<body>
<table>
<tr>
<td><h1>API Field List</h1></td>
</tr>
<tr>
<td>Select fields (blank for all)</td>
</tr>
<tr>
<td>
<select multiple="multiple" id="fieldList" style="height: 300px;">
<option value="Headline">Headline</option>
<option value="Author">Author</option>
<option value="Summary">Summary</option>
<option value="NewsDate">NewsDate</option>
<option value="Image">Image</option>
<option value="NewsCategories">NewsCategories</option>
</select>
</td>
</tr>
<tr>
<td><button id="callGetNews" onclick="getNews();">Get All News Items</button></td>
</tr>
</table>
<p><pre id="output" style="background: #fff;"></pre></p>
</body>
</html>
|
|
| JS |
Copy
|
|---|---|
// Reference the client library
<script src="AdvantageCMS.Resource.WebResource.axd?d=AdvantageAPI.js" type="text/javascript"></script>
// Function to get all news items with only the fields selected (optional).
function getNews() {
// Create request
var req = new AdvContentRequest("News", "en");
// if secure is required
// req.Authenticate = true;
// if calling a different domain (advantage)
// req.Host = 'https://somedomain.com';
// Example of returning only data selected through field list
var fieldList = document.getElementById("fieldList");
for (var i = 0; i < fieldList.options.length; i++) {
if (fieldList.options[i].selected === true) {
req.AddField(fieldList.options[i].value);
}
}
// Example of returning items based on an existing index
// req.Index("Author", "Tom Wolfe", advDataType.String, advCompare.Equals);
// Example of sorting items
// req.AddSort("Author", advDirection.Desc);
// Example of filtering records, not based on an index
// req.AddFilter("NewsDate", "2023/01/01", advDataType.Date, advCompare.GreaterOrEquals);
// Request the content and reference the promise for the success and failure result.
advGetContent(req, showResult, showResult);
// For a synchronous request, use the line below
// var result = await advGetContent(req);
}
function getNewsById() {
var masterId = document.getElementById("txtMasterId").value;
var req = new AdvContentRequestById("news", "en", masterId);
// if secure is required
// req.Authenticate = true;
// if calling a different domain (advantage)
// req.Host = 'https://somedomain.com';
advGetContent(req, showResult, showResult); // Get the data.
}
function showResult(resp) {
var pretty = JSON.stringify(resp.Data, undefined, 2);
document.getElementById('output').innerHTML = "<pre>" + pretty + "</pre>";
}
|
|