A 101 Look Into Our Rest Based API – Helpdesk

This article will provide you with an overview and the knowledge you will need to get started. My goal is to provide specifics, as well as to walk you through a practical example.

First things first, Authenticating via Basic Authentication.

Basic Authentication, as you might have expected, requires credentials. A Username, Password, and an APIKey to be specific!

While the Username and Password should not need an introduction, you might not know exactly what our APIKey represents. Simply put, the ApiKey is a unique identifier assigned to a partner and allows access to the API. Every APIKey is unique and has its own data associated with it. (see sample record below)

APIKey Record

<Name>Redtail Technology</Name>

<URL>http://www.redtailtechnology.com</URL>

Ok, so now you should be wondering, How do I supply the credentials?

Below, you can see that the credentials are supplied in the request header as a string, with each credential separated by a single colon. Don't worry! The credentials are secured via SSL.

"APIKey:Username:Password"
"G5555F31-56Z2-62X7-9PSG-553E0MCD8ATG2:CoolGuy65:L@zypass"

When supplying the credentials, you will want to use base64 encoding to alleviate any woes related to incompatible characters, as well as specify the Basic authentication type. See bolded string in request header example below.(C#)

HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create("https://api2.redtailtechnology.com/crm/v1/rest/contacts/384843/notes");
req.Headers[System.Net.HttpRequestHeader.Authorization] = "Basic " + Convert.ToBase64String(System.Text.Encoding.Default.GetBytes("G5555F31-56Z2-62X7-9PSG-553E0MCD8ATG2:CoolGuy65:L@zypass"));
req.Method = "GET";
req.ContentType = "text/xml";

Your Credentials

While we do provide credentials specific to our partners, for the sake of this example I am providing a working set of credentials for our production server. If your team does not already have a set of credentials for both environments(development and production), please contact our Sales team at 800-206-5030.

Here's a set to play with while you're emailing me...

"APIKey:Username:Password"
"6C135EDF-C37C-4039-AEF3-5DFC079F9E6A:Statementone:sonedemo"

So lets bring it all together with a simple Get Method.

For starters, we will retrieve a contact record's details!

You might ask, where do I find the URI for the specific method? (Fair enough, the services are REST based after all.)

Browsing through our /help page, we will come across the URI we are looking for. Now bare with me here, as the help page will be easier to navigate in the future. However, the listed URI to the left should give you some direction. We are looking for a GET method to obtain CONTACT details for a specific contact. Might /contacts/{contactid} return what you are looking for? _{^{(see graphic below)}}

For production, our base service address is https://api2.redtailtechnology.com/crm/v1/rest.

Alternatively, our development base service address is http://dev.api2.redtailtechnology.com/crm/v1/rest

The URI '/contacts/{contactid}', when coupled with Method Type 'GET', WILL return a contact record's details. Let's give it a shot.

A popular Contact used for testing in our test database is 'Mary Investor'. So we will retrieve her Contact Record by using her ContactID in the URI below.

https://api2.redtailtechnology.com/crm/v1/rest/contacts/{contactid}

https://api2.redtailtechnology.com/crm/v1/rest/contacts/384843

Below is a sample request in C# using our URI, sample credentials, and the method type. The content type "text/json" work equally well.

HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create("https://api2.redtailtechnology.com/crm/v1/rest/contacts/384843");
req.Headers[System.Net.HttpRequestHeader.Authorization] = "Basic " + Convert.ToBase64String(System.Text.Encoding.Default.GetBytes("6C135EDF-C37C-4039-AEF3-5DFC079F9E6A:Statementone:sonedemo"));
req.Method = "GET";
req.ContentType = "text/xml";

//and here's the response stream.
HttpWebResponse resp = (HttpWebResponse)req.GetResponse();
System.IO.StreamReader sr = new System.IO.StreamReader(resp.GetResponseStream());

So wait, you want a simple tool to test our methods with or to nail the concept down?

Fiddler is a great FREE tool for testing. If you are not at all familiar with Fiddler, I will provide brief tutorial for our purposes below.

Just like the example before it, you need to provide the request URI, credentials(base64 encoded) and method type. Content type can be specified optionally.

Using Fiddler, select the Composer tab and enter information similar to the following image below. Remember, the credentials need to be base64 encoded!

You will want to navigate to the Inspectors tab to view the results.

The Raw section is great for giving you a string of the results. However, for the sake of readability, it is also nice to select the content type that you may or may not have provided in the Request Header.

For a GET method, its as simple as that!

So, great...you can retrieve a record, but what if you want to input information?

Well, that's where PUT methods become involved.

Put methods are more complex, as a request body is required in the call. You will have to use the appropriate data types for each of the fields. I would suggest first performing a GET method to retrieve a record similar to the one you would like to input, as this should prove useful in constructing the PUT's request body.

Below is the request header. Be sure to spot the differences between the GET and PUT requests. In the request header, you should also notice that the URI's {ContactID}= 0. When using PUT methods via our API, supplying 0 as a Record Identifier in the URI will result in the Method creating a NEW record. However, if we specified the ContactID as 384843, we would be updating the record where ContactID = 384843, aka Mary Investor.

HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create("https://api2.redtailtechnology.com/crm/v1/rest/contacts/0");
req.Headers[System.Net.HttpRequestHeader.Authorization] = "Basic " + Convert.ToBase64String(System.Text.Encoding.Default.GetBytes("6C135EDF-C37C-4039-AEF3-5DFC079F9E6A:statementone:sonedemo"));
req.Method = "PUT";
req.ContentType = "text/json";

And here's the accompanying Request Body. Notice that the content type above reflects the string reqJSON used below.

string reqJSON = "{\"CategoryID\":5383,\"ClientID\":0,\"DatabaseID\":41974,\"DateOfBirth\":\"\\/Date(1227011828560-0800)\\/\",\"Firstname\":\"Mary\",\"Gender\":\"F\",\"Lastname\":\"Investor\",\"MaritalStatus\":\"M\",\"Middlename\":\"J\",\"SourceID\":2643,\"StatusID\":8169,\"TypeID\":\"I\"}";
byte[] reqBody = System.Text.Encoding.ASCII.GetBytes(reqJSON);

//Request Stream
req.GetRequestStream().Write(reqBody, 0, reqBody.Length);

//and here's the response stream.
HttpWebResponse resp = (HttpWebResponse)req.GetResponse();
System.IO.StreamReader sr = new System.IO.StreamReader(resp.GetResponseStream());

Comments