Making Requests

The following guide is meant to provide a basic understanding of making REST requests using the Telligent Community REST API.  We recommend always making requests over HTTPS.  To prevent authentication headers and data from being intercepted, it is recommended to always use HTTPS to authenticate with your Telligent Community website.

[toc]

GET

GET requests are used to request a LIST of entities or to SHOW details for one entity. A GET request is the simplest HTTP method. In this kind of request, all data is passed in the URL. The easiest way to understand a GET request is by comparing it to what happens when you type a URL into the address bar of your browser and click Go: Your browser makes a GET request to that URL, retrieves the results returned by the Web site, and displays the results to you. A GET request sent to a Web service works the same way, except the request is usually performed via code.

Sample SHOW user request using the Show User REST Endpoint.

// replace the "admin" and "Admin's API key" with your valid user and apikey!
var adminKey = String.Format("{0}:{1}", "Admin's API key", "admin");
var adminKeyBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(adminKey));

var request = WebRequest.Create("https://mytelligentcommunitysite.com/api.ashx/v2/{0}.json",
    "username" // Username of the user we are returning
    ) as HttpWebRequest;
request.Method = "GET";
request.Headers.Add("Rest-User-Token", adminKeyBase64);

var response = request.GetResponse() as HttpWebResponse;
string text = null;
using (var sr = new StreamReader(response.GetResponseStream()))
{
    text = sr.ReadToEnd();
}

Console.WriteLine(text);

POST

POST requests are translated as CREATE requests. Unlike GET requests, HTTP POST requests contain their data in the body of the request. If you have ever submitted a form online, you have probably submitted an HTTP POST request. You can't create a POST request to a Web service directly from your browser without using a form, code, or browser plug-in.

The easiest way to demonstrate a POST request is by using a little bit of C# code. The following code snippet demonstrates submitting a POST request to the Telligent Community platform's v2 Web services Users endpoint. Performing the POST with the accompanying data to the Users endpoint will CREATE a new user:

Sample POST request using the Create User REST Endpoint.

// replace the "admin" and "Admin's API key" with your valid user and apikey!
var adminKey = String.Format("{0}:{1}", "Admin's API key", "admin");
var adminKeyBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(adminKey));

var request = WebRequest.Create("https://mytelligentcommunitysite.com/api.ashx/v2/users.json") as HttpWebRequest;
request.Method = "POST";
request.Headers.Add("Rest-User-Token", adminKeyBase64);
request.ContentType = "application/x-www-form-urlencoded";

var data = string.Format("Username={0}&Password={1}&PrivateEmail={2}", 
    "username", // Username of the user we are creating
    "password", // Password of the user we are creating
    "username@mysite.com" // Private email address of the user we are creating
    );
byte[] bytes = Encoding.UTF8.GetBytes(data);

var requestStream = request.GetRequestStream();
requestStream.Write(bytes, 0, bytes.Length);
requestStream.Close();

var response = request.GetResponse() as HttpWebResponse;
string text = null;
using (var sr = new StreamReader(response.GetResponseStream()))
{
    text = sr.ReadToEnd();
}

Console.WriteLine(text);

PUT

PUT requests are translated as UPDATE request. Like a POST request, a PUT request's data is included within the message body. Performing a PUT request is very similar to performing a POST request. To update a user with an ID of 2132, you would perform a PUT request using code similar to the POST example above to the http://localhost/api.ashx/v2/users/2132.xml endpoint.

Some Web servers, including IIS, disable PUT and DELETE requests by default for security purposes. For this reason the Telligent Community platform's v2 Web services provides overloads of the POST method for PUT operations that allow you to perform PUT- like functions by making a POST request with a custom HTTP header of Rest-Method: PUT

Sample PUT request using the Update User REST Endpoint.

// replace the "admin" and "Admin's API key" with your valid user and apikey!
var adminKey = String.Format("{0}:{1}", "Admin's API key", "admin");
var adminKeyBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(adminKey));

var request = WebRequest.Create(string.Format("https://mytelligentcommunitysite.com/api.ashx/v2/users/{0}.json", 
    "username" // Username of the user we are updating
    )) as HttpWebRequest;
request.Method = "POST";
request.Headers.Add("Rest-User-Token", adminKeyBase64);
request.Headers.Add("Rest-Method", "PUT");
request.ContentType = "application/x-www-form-urlencoded";

// We are only updating the users Private Email
var data = string.Format("PrivateEmail={0}", "username.updated@mysite.com");
byte[] bytes = Encoding.UTF8.GetBytes(data);

var requestStream = request.GetRequestStream();
requestStream.Write(bytes, 0, bytes.Length);
requestStream.Close();

var response = request.GetResponse() as HttpWebResponse;
string text = null;
using (var sr = new StreamReader(response.GetResponseStream()))
{
    text = sr.ReadToEnd();
}

Console.WriteLine(text);

DELETE

Used for DELETE requests. If you make a DELETE request to http://localhost/api.ashx/v2/users/2132.xml, you are asking that the user with ID 2132 be removed.

Some Web servers, including IIS, disable PUT and DELETE requests by default for security purposes. For this reason the Telligent Community platform's v2 Web services provides overloads of the POST method for DELETE operations that allow you to perform DELETE-like functions by making a POST request with a custom HTTP header of Rest-Method: DELETE.

Sample DELETE user request using the Delete User REST Endpoint.

// replace the "admin" and "Admin's API key" with your valid user and apikey!
var adminKey = String.Format("{0}:{1}", "Admin's API key", "admin");
var adminKeyBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(adminKey));

var request = WebRequest.Create(string.Format("https://mytelligentcommunitysite.com/api.ashx/v2/users/{0}.xml?includetypes=true", 
    "username" // Username of the user we are deleting
    )) as HttpWebRequest;
request.Method = "POST";
request.Headers.Add("Rest-User-Token", adminKeyBase64);
request.Headers.Add("Rest-Method", "DELETE");
request.ContentLength = 0;

var response = request.GetResponse() as HttpWebResponse;
string text = null;
using (var sr = new StreamReader(response.GetResponseStream()))
{
    text = sr.ReadToEnd();
}

Console.WriteLine(text);

Using the Batch REST Endpoint

The BATCH REST Endpoint can be used to make a series of REST request in a batch.  Up to 100 requests can be made in one batch request.  The batch request can also be set to run sequential.  When running sequential if one request fails, the remaining requests will not be executed.  Using this endpoint can offer performance by reducing the number of hops between the external application and Telligent Community as well as by allowing requests to run simultaneously.

The following sample uses the BATCH REST endpoint to create both a user and a group in one request.

// replace the "admin" and "Admin's API key" with your valid user and apikey!
var adminKey = String.Format("{0}:{1}", "Admin's API key", "admin");
var adminKeyBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(adminKey));

var request = WebRequest.Create("https://mytelligentcommunitysite.com/api.ashx/v2/batch.json") as HttpWebRequest;
request.Method = "POST";
request.Headers.Add("Rest-User-Token", adminKeyBase64);
request.ContentType = "application/x-www-form-urlencoded";

var userData = string.Format("Username={0}&Password={1}&PrivateEmail={2}", 
    "username", // Username of the user we are creating
    "password", // Password of the user we are creating
    "username@mysite.com"); //Private email addres of the user we are creating

var groupData = string.Format("Name={0}&GroupType={1}", 
    "name", // Name of the group we are creating
    "Joinless"); // Type of group we are creating

var batchData =
    string.Format(
        "_REQUEST_0_URL={0}&_REQUEST_0_METHOD={1}&_REQUEST_0_DATA={2}&_REQUEST_1_URL={3}&_REQUEST_1_METHOD={4}&_REQUEST_1_DATA={5}",
        HttpUtility.UrlEncode("~/api.ashx/v2/users.json"), 
        "POST", 
        HttpUtility.UrlEncode(userData), 
        HttpUtility.UrlEncode("~/api.ashx/v2/groups.json"), 
        "POST", 
        HttpUtility.UrlEncode(groupData));

byte[] bytes = Encoding.UTF8.GetBytes(batchData);

var requestStream = request.GetRequestStream();
requestStream.Write(bytes, 0, bytes.Length);
requestStream.Close();

var response = request.GetResponse() as HttpWebResponse;
string text = null;
using (var sr = new StreamReader(response.GetResponseStream()))
{
    text = sr.ReadToEnd();
}

Console.WriteLine(text);

Using the above sample, the request can be made to run sequentially but adding the &Sequential=true to the batchData querystring.

var batchData =
string.Format(
    "_REQUEST_0_URL={0}&_REQUEST_0_METHOD={1}&_REQUEST_0_DATA={2}&_REQUEST_1_URL={3}&_REQUEST_1_METHOD={4}&_REQUEST_1_DATA={5}&Sequential=true",
    HttpUtility.UrlEncode("~/api.ashx/v2/users.json"), 
    "POST", 
    HttpUtility.UrlEncode(userData), 
    HttpUtility.UrlEncode("~/api.ashx/v2/groups.json"), 
    "POST", 
    HttpUtility.UrlEncode(groupData));

Using the Scripting REST Endpoint

The Scripting REST Endpoint is used to execute widgets through REST.  The code sample is the widget used in the sample GET and POST requests.  The Scripting REST Endpoint offers performance advantages of  being able to make multiple API calls in one REST API call.  It also allows you to reduce the size of the HTTP response by only including fields you really need.  It also allows for responses to be pre-rendered and can return any data type it wants: HTML, CSV, XML, JSON, etc.

GET

Create a new widget by going to Administration > Interface > Widgets.  Once the widget is created you will be shown the overview page where you can click the Show Details link to grab the Widget ID value that will be used with your Scripting REST Endpoint.  To learn more about widgets, see the Widgets portion of this guide.  

The following sample widget accepts the QueryString parameters ContentId and ContentTypeId and will return a JSON response which will include all comments along with any likes on the comments themselves for the ContentId and ContentTypeId passed in.

$core_v2_page.SetContentType('application/json')

#set ($ContentId = $core_v2_utility.ParseGuid($core_v2_page.GetQueryStringValue('ContentId')))
#set ($ContentTypeId = $core_v2_utility.ParseGuid($core_v2_page.GetQueryStringValue('ContentTypeId')))

#if (!$core_v2_page.IsPost && $ContentId && $ContentTypeId)
#set($comments = $core_v2_comments.List("%{ContentId = $ContentId, ContentTypeId = $ContentTypeId}"))
    {"Comments": [
        #foreach($comment in $comments)
            #before
                {
            #each
            "Comment":{
                #set($likes = $core_v2_like.List("%{ContentId = $comment.CommentId, ContentTypeId = $core_v2_comments.ContentTypeId}"))
                #if ($likes.HasErrors())
    		        $core_v2_page.SendJsonError($likes.Errors)
    		    #else
                    "ContentId": "$comment.ContentId","ContentTypeId": "$comment.ContentTypeId","Body": "$comment.Body","UserId": "$comment.UserId","Likes": [
                            #foreach($like in $likes)
                                #before
                                {
                                #each
                                    "Like":{"UserId":"$like.UserId","CreatedDate":"$like.CreatedDate"}
                                #after
                                }
                            #end
                            ]
            #after
                }
                #end
            }
        #end
    ]}
#end

The following sample GET request calls the sample widget using the Scripted REST Endpoint.  

// replace the "admin" and "Admin's API key" with your valid user and apikey!
var adminKey = String.Format("{0}:{1}", "Admin's API key", "admin");
var adminKeyBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(adminKey));

var request = WebRequest.Create(string.Format("https://mytelligentcommunitysite.com/api.ashx/v2/scripted?Id={0}&ContentId={1}&ContentTypeId={2}", 
    "709a35f5-150e-443a-8483-4907a3efec60", //Widget ID of the widget we are calling
    "BC21522C-39D8-4020-B14A-DA623B9F2C64", //ContentId of the item we are trying to retrieve comments on
    "6B577B8C-0470-4E20-9D29-B6772BF67243" //ContentTypeId of the item we are trying to retrieve comments on
    )) as HttpWebRequest;
request.Method = "GET";
request.Headers.Add("Rest-User-Token", adminKeyBase64);
request.ContentType = "application/x-www-form-urlencoded";

var response = request.GetResponse() as HttpWebResponse;
string text = null;
using (var sr = new StreamReader(response.GetResponseStream()))
{
    text = sr.ReadToEnd();
}

Console.WriteLine(text);

POST

Create a new widget by going to Administration > Interface > Widgets.  Once the widget is created you will be shown the overview page where you can click the Show Details link to grab the Widget ID value that will be used with your Scripting REST Endpoint.  To learn more about widgets, see the Widgets portion of this guide.  

The following sample widget accepts the QueryString parameters ContentId and ContentTypeId and create a like on the associated content.  The response will be return as JSON.

$core_v2_page.SetContentType('application/json')

#set ($ContentId = $core_v2_utility.ParseGuid($core_v2_page.GetQueryStringValue('ContentId')))
#set ($ContentTypeId = $core_v2_utility.ParseGuid($core_v2_page.GetQueryStringValue('ContentTypeId')))

#if ($core_v2_page.IsPost && $ContentId && $ContentTypeId)
    #set($likeResponse = $core_v2_like.Create($ContentId, $ContentTypeId))
    {"Like": {"UserId":"$likeResponse.UserId","ContentId":"$likeResponse.ContentId","CreatedDate":"$likeResponse.CreatedDate"}}
#end

The following sample POST request calls the sample widget using the Scripted REST Endpoint.