Using the Agility.Web REST API

Follow

There are many cases where you may need to interact with your website content outside of your
website code or through any Content Import context. Cases include mobile apps, traditional software applications, other websites etc. Using the REST API, you can easily integrate your Agility content into any client that has the ability to make calls over the web.


The REST API uses specific URL schemes to request data, and your web server will return the appropriate content in a JSON format. It is important to note that all REST API calls will hit one of your deployed web servers that must be set up as a syncing web server in Agility.

Under the hood, the REST API uses the Agility Content Files stored in the Agility Content Repository on the web server.


Content that can be retrieved via the REST API include:

  • Content Lists
    • Returns a list
  • Content Items
    • Returns a single content item
  • Image Galleries
    • Returns a single gallery
  • Settings
    • Default Language
    • Languages (list)
    • GlobalCss
    • Top Scripts
    • BottomScripts
    • EnableOutputCache
    • OutputCacheSettings

*At the time of this writing, there is no implementation to request Pages

REST API Setup

All REST API requests need to be made directly to your web server which is assumed to be publicly
accessible via a URL. There is no additional setup required. The default base API route is “~/api”,
however, this can be overridden by placing the following within your route table:

ApiRouting.AddAgilityApiRoutes(routes, "custom-api-route");

The URL Schemes

Each request to the API must contain a URL scheme made up of the path which will dictate what type of content to retrieve as well as some required and optional query string parameters.

Required Query String Parameters

- time – Unix timestamp
- hash – SHA1 hash of the WebsiteName, SecurityKey, and time (Unix timestamp)

Optional Query String Parameters (for Get Content List only):

- sort – i.e. “Title ASC”
- filter – standard DataView row filter syntax
- skip – integer
- take – integer (there is a maximum page size of 1000)

Request Paths

Get Content List
- /api/content/{languageCode}/{referenceName}

Get Content Item
- /api/content/{languageCode}/{contentID}

Get Gallery
- /api/galleries/{galleryID}

Get Settings
- /api/settings

Sample Request:
http://yourwebsite.com/api/content/enus/Blogs?sort=Title%20ASC&filter=Category%3DFun&skip=10&take=5&time=1411006077&hash
=04323a2eff88e6b3e78eff0a2fdd10d0237a9715

Getting Content via the REST API

The following code snippet represents sample code to make a request to the Agility.Web REST API using .NET.

//replace with your local site or stage server
string website = "http://localhost:59679";
string languageCode = "en-us";
string referenceName = "Products";
string websiteName = "James Sample MVC"; //replace with your site name
string securityKey = "insert security key here"; //replace with your securityKey
string url = string.Format("{0}/api/content/{1}/{2}", website, languageCode, referenceName);

//get unix timestamp

DateTime unixEpoch = new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
DateTime dt = DateTime.UtcNow;
long time = (long)(dt - unixEpoch).TotalSeconds;

//calculate hash
string hashSource = string.Join(".", new[] { websiteName, securityKey, time.ToString("d") });
SHA1 sha1 = SHA1.Create();
byte[] sha1Bytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(hashSource));
StringBuilder sb = new StringBuilder();

foreach (byte b in sha1Bytes)
{
sb.Append(b.ToString("x2"));
}

string hash = sb.ToString();

//set the required querystring params
string hashQ = string.Format("time={0}&hash={1}", time, hash);

//add the time and hash querystrings
url = string.Format("{0}?{1}", url, hashQ);
using (HttpClient client = new HttpClient())
{

client.Timeout = new TimeSpan(0, 0, 60); //60 seconds
var res = client.GetAsync(url);
var content = string.Empty;

try
{
if (!res.Result.IsSuccessStatusCode)
{
dynamic err = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(content);
Console.WriteLine(string.Format("An error occurred: {0}", err.Message));
Console.ReadKey();

}
else {
content = res.Result.Content.ReadAsStringAsync().Result;
Console.WriteLine(content);
Console.ReadKey();
}
JsonConvert.DeserializeObject<dynamic>(content);
} catch(Exception ex) {
Console.WriteLine(string.Format("An error occurred: {0}", ex.ToString()));
Console.ReadKey();
}

}
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.