هذه المقالة متوفرة أيضا باللغة العربية، اقرأها هنا.

Read more about URL Shortening Services here.

Source- Elsheimy.Samples.ShortenSvcs.zip

Contents

Contents of this article:

• Contents
• Overview
• Introduction
• API
• What’s next

Overview

Another article of our endless series that talks about accessing URL shortening services programmatically.

This article is talking about 1click.at shortening service, how you can use it, and how to access it via your C#/VB.NET application.

Introduction

We can’t say that 1click.at is not one of the well-known services nor it has anything special, however, as long as it provides an API we are very interested in it.

When you visit service website, http://1click.at, you can see that nothing easier from 1click.at, just push your long URL into the text box and click the shortening button.

API

1click.at provides you a very simple easy-to-use API. This API contains only one function that’s used for shortening URLs. Another good thing is that this function doesn’t require any kind of authentication for users. Therefore, you need just to send it your long URL (as you did with the website.)

The shortening function function is called http://1click.at/api.php, it accepts 3 arguments:

1. action:
   Yet, it can accept only one value, shorturl, which orders the function to shorten the specified url.
2. url:
   The long URL to be shortened.
3. format:
   The format of the returned data from the function. Can be simple, xml, or json.

As you know, the .NET BCL doesn’t support JSON (some third-party components do,) and thus, we won’t cover JSON data returned from the function. Rather, we’ll concentrate on plain and XML data returned.

When the format of this function is XML, the returned data, if the function succeeded, is like the following if this is your first time you shorten this URL:

<result>
    <url>
        <keyword>GFbA1zL</keyword>
        <url>http://WithDotNet.net</url>
        <date>2010-12-17 20:14:04</date>
        <ip>0.0.0.0</ip>
    </url>
    <status>success</status>
    <message>http://WithDotNet.net added to database</message>
    <shorturl>http://1click.at/GFbA1zL</shorturl>
    <statusCode>200</statusCode>
</result>

If, however, this isn’t your first time you shorten this URL, you would get data like this:

<result>
    <status>fail</status>
    <code>error:url</code>
    <message>http://WithDotNet.net already exists in database</message>
    <shorturl>http://1click.at/GFbA1zL</shorturl>
    <statusCode>200</statusCode>
</result>

Anyway, you can retrieve the value of shorturl and forget about the rest.

Now, let’s try this function. We’ll try to shorten the URL http://WithDotNet.net with our function. First, connect the arguments, e.g. http://1click.at/api.php?action=shorturl&url=http://WithDotNet.net&format=xml. Now copy this address and paste it into your favorite browser. If everything was OK, you should see the short URL after clicking ‘Go’ in the browser toolbar.

Now, let’s do it in C# and VB.NET. Check the following function that tries to shorten long URLs via the id.gd API:

// C#

string Shorten(string url, bool xml)
{
    url = Uri.EscapeUriString(url);
    string reqUri =
String.Format("http://1click.at/api.php?action=shorturl&url={0}&format={1}",
        url, xml ? "xml" : "simple");

    HttpWebRequest req = (HttpWebRequest)WebRequest.Create(reqUri);
    req.Timeout = 10000; // 10 seconds

    // if the function fails and format==txt throws an exception
    Stream stm = req.GetResponse().GetResponseStream();

    if (xml)
    {
        XmlDocument doc = new XmlDocument();
        doc.Load(stm);

        // error checking for xml
        if (doc["result"]["statusCode"].InnerText != "200")
            throw new WebException(doc["result"]["statusCode"].InnerText);

        return doc["result"]["shorturl"].InnerText;
    }
    else // Text
        using (StreamReader reader = new StreamReader(stm))
            return reader.ReadLine();
}

' VB.NET

Private Function Shorten(url As String, xml As Boolean) As String
	url = Uri.EscapeUriString(url)
	Dim reqUri As String = "http://1click.at/api.php?action=shorturl&url={0}&format={1}"
	If (xml) Then
		reqUri = String.Format(reqUri, url, "xml")
	Else
		reqUri = String.Format(reqUri, url, "simple")
	End If

	Dim req As HttpWebRequest = DirectCast(WebRequest.Create(reqUri), HttpWebRequest)
	req.Timeout = 5000
	Dim stm As Stream = req.GetResponse().GetResponseStream()

	If xml Then
		Dim doc As New XmlDocument()
		doc.Load(stm)

		' error checking for xml
		If doc("result")("statusCode").InnerText <> "200" Then
			Throw New WebException(doc("result")("statusCode").InnerText)
		End If

		Return doc("result")("shorturl").InnerText
	Else
		' Simple
		Using reader As New StreamReader(stm)
			Return reader.ReadLine()
		End Using
	End If
End Function

Notice that we have used the function System.Net.Uri.EscapeUriString() to eliminate unacceptable characters from the URL by encoding them.

Notice too that we have included our code in a Try-Catch block so we can catch exceptions before they blow up our application.

What’s next

Consider reading other articles in this series here.

هذه المقالة متوفرة أيضا باللغة العربية، اقرأها هنا.

Read more about URL shortening services here.

Source- Elsheimy.Samples.ShortenSvcs.zip

Contents

Contents of this article:

• Contents
• Overview
• Introduction
• API
• WCF Services
  • Squeeze Service
  • Reporting Service
• RESTful Services
  • Squeeze Service
  • Reporting Service
• Source Code
• What’s next

Overview

This is another article of our URL shortening services series. This article is talking about X.co shortening service provided by Go Daddy. If you don’t know how to access this service from your .NET application, then it’s the time to.

We’ll have a complete discussion of the WCF services offered by X.co. Then, we’ll consider the RESTful interfaces provided.

Introduction

Today we are going to talk about one of the most popular URL shortening services on the web now; it’s the new X.co provided by Go Daddy, the dominating domain names and web hosting service provider.

While X.co is considered very new since it has released just few months ago, it gained support from users worldwide very quickly, and now it’s one of the most popular shortening services exist in the web. Although the interface provided to users doesn’t offer great functionality, the API interface it provides really deserves respect since it’s one of the most easiest yet powerful APIs (for shortening services) exist on the web now.

API

The most noticeable thing about X.co API is that unlike other APIs it’s based on ASP.NET and WCF (WOW!) Moreover, the WCF service provides you a RESTful interface. Thus, you end up with two interfaces, one is based on WCF, and other is a REST web service.

You might not be familiar with WCF or other new technologies related to versions higher than .NET 2.0, don’t worry it’s just a matter of names! You use WCF services the same way as with ordinary Web Services.

In this writing, we’ll first talk about WCF/Web service interfaces provided to you by X.co. After that, we’ll have a look at how RESTful interfaces fit in the picture.

Before we begin our discussion, you’ll need to grab your API key that’s required by all functions for authentication. To get your API key, first create a free account at http://www.godaddy.com if you don’t have one yet. Figure 1 shows the registration page.

After you complete the registration process, go to http://x.co, login with your username and password, and go to Settings to get your API key. See figure 2.

Notice that this is a secret key and you should keep it away from intruder eyes. This key will be used in all of your work with X.co API.

WCF Services

WCF or Web services, not a big deal, let’s just call it WCF. Our service X.co provides you two WCF services that you can access:

• The shortening (squeezing) service http://api.x.co/Squeeze.svc
• The reporting (and analytics) service http://api.x.co/Reporting.svc

The Squeeze service supports only one function that can be used to shorten (squeeze) long URLs. In fact, the Squeeze service provides other functions too, however, they are either deprecated or for the internal use of Go Daddy. The other service, the Reporting service, supports functions related to reports and analytics of short URLs (like clicks and referrer sites.)

Whatever service you like to use, you must reference it to your projects. To add a reference to a web service to your project, you can use one of two ways. The first and better way is to use Visual Studio. Right-click the Web References node under your project node in Solution Explorer and select Add Web Reference to launch the Add Web Reference dialog (see figure 3.)

The Add Web Reference dialog is now on the top of the IDE, the dialog might appear different in .NET 2.0 than higher versions (see figure 4 and figure 5.) Whatever, write the address of the service that you need to add, click Go so can Visual Studio read service description, write a good name in the Reference Name field that would be the namespace that groups service objects, and finally click Add Reference. Notice that we have used the name xcoapi for the Squeeze service, and xcoapirpt for the Reporting service.

Another approach to get the required source files for the service is to use the svcutil.exe tool that’s used internally by Visual Studio. This is a command tool that generates source files for web and WCF services. You can use this tool as follows:

svcutil.exe http://api.x.co/Squeeze.svc?wsdl /language=C#
svcutil.exe http://api.x.co/Squeeze.svc?wsdl /language=VB

Notice that we have included the address of the discovery (description) WSDL data of the services so that the tool can read it. Remember to select your language in the command.

Squeeze Service

The first function we have today and the only function of the Squeeze service (http://api.x.co/Squeeze.svc) is the Shorten() function that’s used to shorten long URL files. This function simply accepts 2 arguments:

• url:
  The long URL to be shortened.
• apiKey:
  The API key used to authenticate the call.

There’re other functions existing in the Squeeze service but they are either deprecated or reserved for internal use by Go Daddy.

After you ensure that a reference of the service is added to your project (check the previous section) you can start writing your code. The following function accepts the long URL and returned the shortened one that’s -at the time of this writing- is no more than 16 characters (e.g. http://x.co/8Gg8):

// C#

string Shorten(string url, string apiKey)
{
    using (xcoapi.Squeeze sq = new xcoapi.Squeeze())
    {
        return sq.Shorten(url, apiKey);
    }
}

Notice that web services consumes lots of system resources and you should release them as soon as you finish you work with them, that’s why we have used the C# using statement.

Reporting Service

The other service we have is the Reporting service (http://api.x.co/Reporting.svc) that offers you great deal of analytics and reporting functionalities that can be sorted in 3 areas:

• Click count (the number of uses of the short URL)
• Referrer sites (for the short URL)
• Uses by locations (city, region, and country.)

This service supports 5 functions:

• GetTotalMapClick():
  Returns total clicks (uses) of a short URLs.
• GetMapClicksByDates():
  Returns clicks of a short URL made within a given time period grouped by days.
• GetMapClicksByHour():
  Returns clicks of a short URL made today grouped by hours.
• GetMapReferrersByDates():
  Returns referrer links made to the short URL within a given time period grouped by days.
• GetMapLocationsByDates():
  Returns clicks of a short URL made within a given time period grouped by geographic location.

Those five functions are very similar in many ways. First, they all accept two required parameters:

• apiKey:
  Your API key.
• encoded:
  The short code of the short URL. For instance, 8Gg8 of http://x.co/8Gg8. Notice that the short (encoded) code is case-sensitive, http://x.co/8Gg8 is very different from http://x.co/8gg8.

In addition, the last four functions work the same way. They all return arrays of objects. GetMapClicksByHour() for instance returns the number of clicks made today grouped by hours each hour is represented by an object that contain the hour number besides the clicks made in that hour, and all objects are grouped inside one array.

The other functions GetMapClicksByDates(), GetMapReferrersByDates(), and GetMapLocationsByDates() work the same way and accept the same parameters except that they accept four additional parameters represent the begin and the end dates of the time period and whether the date parameters were set or leaved empty.

How can the four parameters help? You can define both and set the two flags to indicate that we need a specific time period. You can also set one of them and set its flag to indicate that you need to start from a specific day and get analytics till now. Notice that you can’t leave both empty.

The following code returns the total number of clicks for a specific short URL:

// C#

int GetTotalClicks(string shortCode, string apiKey)
{
    using (xcoapirpt.ReportingClient rpt = new xcoapirpt.ReportingClient())
    {
        return rep.GetTotalMapClick(apiKey, shortCode);
    }
}

And the following code is the same as the above except that it uses .NET 2.0:

// C#

int GetTotalClicks(string shortCode, string apiKey)
{
    using (xcoapirpt.Reporting rpt = new xcoapirpt.Reporting())
    {
        int totalClicks;
        bool succeeded;
        rep.GetTotalMapClick(apiKey, shortCode, out totalClicks, out succeeded);

        return succeeded ? totalClicks : -1;
    }
}

Notice the slight difference between the two calls (in .NET 2.0 and higher versions.) In .NET 2.0, the returned value is specified as an output parameter.

The following code is somewhat complex than the previous. The following code returns the refer links for our short URL:

// C#

xcoapirpt.ReferrerEventInfo[] GetReferrers
    (string shortUrl, string apiKey, out int totalClicks)
{
    using (xcoapirpt.Reporting rep = new xcoapirpt.Reporting())
    {
        xcoapirpt.ReferrerEventInfo[] results =
            rep.GetMapReferrersByDates(apiKey, shortUrl,
                DateTime.Now - new TimeSpan(7, 0, 0, 0, 0), true, DateTime.Now, true);

        totalClicks = 0;
        foreach (xcoapirpt.ReferrerEventInfo r in results)
            totalClicks += r.TotalSpecified ? r.Total : 0;

        return results;
    }
}

Notice how we specify the start and end date parameters and their flags to get only the last week analytics. Notice also the type of the array returned from the function and how we used it to get the required information.

RESTful Services

If you prefer not to use the WCF services, you can start with the REST interface provided to you by the kind-hearted WCF services. A RESTful service is simply a group of related web functions that has specific formats; some of return plaint text, some return XML data, and others return JSON.

Keep in mind that WCF services are supported natively by .NET framework and thus they are faster and easier to work with.

Squeeze Service

Not surprisingly, our RESTful Squeeze service is provided to us by the address http://api.x.co/Squeeze.svc. This service has two functions to shorten URLs, one is JSON, and the other is plain text.

The first function that returns plain text can be called using the following address:

http://api.x.co/Squeeze.svc/text/{apiKey}?url={url}

Now you have the address and ready with the input, the following function calls the previous function to shorten long URLs:

// C#

string Shorten(string url, string apiKey)
{
    WebRequest req = HttpWebRequest.Create(
        string.Format("http://api.x.co/Squeeze.svc/text/{0}?url={1}",
        apiKey, url));

    req.Timeout = 10000; // 10 seconds

    string shortUrl;
    System.IO.Stream stm;

    stm = req.GetResponse().GetResponseStream();

    using (System.IO.StreamReader rdr = new System.IO.StreamReader(stm))
    {
        return rdr.ReadToEnd();
    }
}

Reporting Service

Likewise, the Reporting service has the following address: http://api.x.co/Squeeze.svc. This service provides you with many functions like its WCF counterpart, however, all of them are JSON expect one is plain text. Because JSON is not natively supported by .NET Framework and thus requires the use of other 3^rd party components (e.g. Json.NET) we won’t consider those endpoints. However, we have our total clicks function that returns plain text:

// C#

int GetTotalClicks(string shortCode, string apiKey)
{
    WebRequest req = HttpWebRequest.Create(
        string.Format("http://x.co/Reporting.svc/map/{0}/{1}/total",
        apiKey, shortCode));

    req.Timeout = 10000; // 10 seconds

    System.IO.Stream stm;

    stm = req.GetResponse().GetResponseStream();

    using (System.IO.StreamReader rdr = new System.IO.StreamReader(stm))
    {
        return int.Parse(rdr.ReadToEnd());
    }
}

Again, the short code is the only required piece of the short URL, you do not need to include the http://x.co/ (actually, you can’t!)

Source Code

Download the source code files from here.

What’s next

Consider reading more about URL shortening services here.

هذه المقالة متوفرة أيضا باللغة العربية، اقرأها هنا.

Read more about URL shortening services here.

Source- Elsheimy.Samples.ShortenSvcs.zip

Contents

Contents of this article:

• Contents
• Overview
• Introduction
• Description
• API
• Where to go next

Overview

Just another article of the URL shortening services series.

Today, we are going to talk about another hot and easy-to-use service, it’s Tweetburner. If you haven’t used it before, then it’s the time to.

We’re going to discuss how to use Tweetburner first. After that, we’ll inspect its API and learn how to use it in your .NET application.

Introduction

Again, one of the most popular URL shortening services ever.

Today is dedicated for Tweetburner (known as twurl,) one of the hot, simple, and easy-to-use shortening services that you can compare to is.gd.

Description

When you visit Tweetburner website (via http://tweetburner.com or http://twurl.nl,) you can see that it allows users to register to gain more functionalities (specifically, link analytics.) However, at the time of this writing, the account page is disabled for technical issues and nothing interesting would happen if you register there.

One of the hot features of Tweetburner is that it allows you to post your links to twitter (you guessed) and friendfeed as soon as they’re shortened just click ‘Share this link’ before you leave the page.

Unfortunately, you can’t benefit from this sharing feature programmatically, but of course, you can create your own routines.

After shrinking your URL, you get a new short link about 22 characters long (18 in is.gd) prefixed with http://twurl.nl.

API

Actually, Tweetburner doesn’t help you with an API. Instead, it provides you with a simple web page (used for shortening URLs) that you can access it from your code and get your short URLs.

Let’s try it! Browse to our key page, http://tweetburner.com/links, and push your long URL and click the shortening button.

So how you can access this page via your .NET application and fill in its single field? Let’s get the idea! If you check the API documentation page, you might find that you are required just to request information from that page, post it the required URL via a simple string included in the request body, link[url]={0} (where {0} is the long URL, and just wait for the response that would contain the short URL of course if the function succeed.

Do you find that ‘link[url]={0}’ strange? Try this with me! Browse to our page, http://tweetburner.com/links, and save it as HTML in your PC (not required, just grab its HTML code.)

Sure we are interested on this magical text box, so scroll down to its definition that looks like this:

Notice that the text box is given the name ‘link[url]’, that’s why we push ‘link[url]={0}’ on the request body. Given that hot information, you can push any data to any web form, just get the information required.

Now, let’s code! The next function browses to our page, http://tweetburner.com/links, pushes the long URL specified, and gets the short URL back from the server. (Remember to include the namespace System.Net for the code to work properly.)

// C#

string Short(string url)
{
    url = Uri.EscapeUriString(url);

    HttpWebRequest req = (HttpWebRequest)WebRequest.Create("http://tweetburner.com/links");
    req.Timeout = 5000;
    req.Method = "POST";
    req.ContentType = "application/x-www-form-urlencoded";

    byte[] buffer = System.Text.Encoding.UTF8.GetBytes("link[url]=" + url);
    req.ContentLength = buffer.Length;

    System.IO.Stream ios = req.GetRequestStream();
    ios.Write(buffer, 0, buffer.Length);

    try
    {

        using (System.IO.StreamReader reader =
            new System.IO.StreamReader(req.GetResponse().GetResponseStream()))
        {
            return reader.ReadLine();
        }
    }
    catch (WebException ex)
    {
        return ex.Message;
    }
}

' VB.NET

Function Shorten(ByVal url As String) As String
    url = Uri.EscapeUriString(url)

    Dim req As HttpWebRequest = _
        CType(WebRequest.Create("http://tweetburner.com/links"), HttpWebRequest)
    req.Timeout = 5000
    req.Method = "POST"
    req.ContentType = "application/x-www-form-urlencoded"

    Dim buffer() As Byte = _
        System.Text.Encoding.UTF8.GetBytes("link[url]=" + url)
    req.ContentLength = buffer.Length

    Dim ios As System.IO.Stream = req.GetRequestStream()
    ios.Write(buffer, 0, buffer.Length)

    Try
        Dim reader As System.IO.StreamReader = _
            New System.IO.StreamReader(req.GetResponse().GetResponseStream())

        Dim retValue As String = reader.ReadLine()

        reader.Close()

        Return retValue
    Catch ex As WebException
        Return ex.Message
    End Try
End Function

Notice that we have specified the POST method because it’s required if you are going to change some data in the server. It’s worth mentioning too that we have set the content type to application/x-www-form-urlencoded because it’s required if you are going to push data to a web form (it’s usually perfect for all web forms except file-uploads.)

In addition, we have included the input required in the request stream.

What’s next

Some other articles about URL shortening services are available here.

هذه المقالة متوفرة أيضا باللغة العربية، اقرأها هنا.

Read more about URL Shortening Services here.

Source- Elsheimy.Samples.ShortenSvcs.zip

Contents

Contents of this article:

• Contents
• Overview
• Introduction
• API
• What’s next

Overview

Another article of our series that talks about accessing URL shortening services programmatically.

This article is talking about is.gd shortening service, how you can use it, and how to access it via your C#/VB.NET application.

Introduction

is.gd is one of the most popular shortening services ever in the web because of its simple interface and its easy-to-use API.

When you visit service website, http://is.gd, you can see that nothing easier from is.gd, just push your long URL into the text box and click the shortening button.

API

is.gd provides you a very simple easy-to-use API. This API contains only one function that’s used for shortening URLs. Another good thing is that this function doesn’t require any kind of authentication for users. Therefore, you need just to spam it with your long URL (as you did with the website.)

This glorious function is called http://is.gd/api.php, it accepts only a single argument, longurl, which can be set to the long URL you need to shorten. When you call the function, it simply returns the shortened URL as plain text (no more overhead.)

Now, let’s try this function. We’ll try to shorten the URL http://JustLikeAMagic.com with our function. First, connect the arguments, http://is.gd/api.php?longurl=http://JustLikeAMagic.com. Now copy this address and paste it into your favorite browser. If everything was OK, you should see the short URL after clicking €˜Go’ in the browser toolbar.

Now, let’s do it in C# and VB.NET. Check the following function that tries to shorten long URLs via the id.gd API:

// C#

string Shorten(string url)
{
    url = Uri.EscapeUriString(url);
    string reqUri = String.Format(@"http://is.gd/api.php?longurl={0}", url);

    HttpWebRequest req = (HttpWebRequest)WebRequest.Create(reqUri);
    req.Timeout = 5000;

    try
    {
        using (System.IO.StreamReader reader =
            new System.IO.StreamReader(req.GetResponse().GetResponseStream()))
        {
            return reader.ReadLine();
        }
    }
    catch (WebException ex)
    {
        return ex.Message;
    }
}

' VB.NET

Function Shorten(ByVal url As String) As String

    url = Uri.EscapeUriString(url)
    Dim reqUri As String = _
        String.Format("http://is.gd/api.php?longurl={0}", url)
    Dim req As WebRequest = WebRequest.Create(reqUri)
    req.Timeout = 5000

    Try
        Dim reader As System.IO.StreamReader = _
            New System.IO.StreamReader(req.GetResponse().GetResponseStream())

        Dim retValue As String = reader.ReadLine()
        reader.Dispose()

        Return retValue
    Catch ex As WebException
        Return ex.Message
    End Try

End Function

Notice that we have used the function System.Net.Uri.EscapeUriString() to eliminate unacceptable characters from the URL by encoding them.

Notice too that we have included our code in a Try-Catch block so we can catch exceptions before they blow up our application.

What’s next

Consider reading other articles in this series here.

هذه المقالة متوفرة أيضا باللغة العربية، اقرأها هنا.

Read more about URL shortening services here.

Source- Elsheimy.Samples.ShortenSvcs.zip

Contents

Contents of this article:

• Contents
• Overview
• Introduction
• Accessing the API
• Authentication
• .NET Support
• Encoding
• Sample
• Where to Go Next
• Poll: What are your favorite URL shortening services?

Overview

This is the first article of our series that talks about accessing URL shortening services programmatically.

Here we introduce new concepts like the REST API. We also have a brief discussion of URL shortening services APIs and how you can access them.

In addition, we are going to talk about .NET support for the REST API and tools and techniques available that would help us during our journey through the API.

A working example built using C# and WinForms is available at the end of this article.

This article is the base for all other articles. Articles other than this discuss specific services and their APIs. We will make use of code and techniques discussed here throughout the rest of articles.

Let’s go!

Introduction

URL shortening services are very popular these days since web addresses tend to be very long and very difficult to be exchanged via email or other micro-blogging services like Twitter.

Today, there’re tenths of URL shortening services spread out all over the web. Most of them are listed in the following articles:

• URL Toolbox: 90+ URL Shortening Services
• URL Shortening Services, The Ultimate List

In this series, we are going to talk about how to consume URL shortening services in your .NET application. In other words, we will discuss how to program URL shortening services; we mean how to access them programmatically. In addition, we will have a brief discussion of each service and its unique features.

How we will go through this discussion? This is going to be a series of articles published regularly. Each article discusses a given shortening service from the following list (updated regularly, expect new services to be added):

• is.gd
• twurl.nl
• cli.gs
• bit.ly

The preceding list may not be comprehensive, many other popular services exist. However, not all shortening services have APIs! The preceding list contains the shortening services we know that allow developers to consume their functionalities via an exposed API.

Before we start with a specific service, let’s have a brief discussion of features of the API and how we can access them.

Accessing the API

Most APIs in the web are just REST (Representational State Transfer) web services. A REST web service is simply a collection of functions (HTTP endpoints) that can be used to retrieve data in a variety of formats (optional.)

Given an endpoint (function) like http://ab.c/api/shrink, we could supply the required input arguments as query strings in the URL. For example, we could shorten the URL www.google.com using a call to the HTTP endpoint http://ab.c/api/shrink?url=www.google.com supplied with the required information. It is worth mentioning that every service has its own API functions and arguments. Although they all do the same thing (shortening the URL,) they differ in function and argument names.

When you call a web function, you just end up with the results in the format used in that function (XML, Atom, JSON, etc.) The function could also return plain text! It’s all about the function documentation that you should check carefully before calling the function. In addition, the returned value from a function may also contain error details if the function didn’t success.

Keep in mind that API calls are limited and you can’t just leave the shortening code in an end-less loop! Other limitations of specific APIs should be discussed later.

Authentication

Most URL shortening services allow users to consume the service without being registered, some of allow users to register, and others not. Many other services require users to be registered in order to use the service.

Likewise, service APIs may or may not require user authentication. Some services give the user an API key that can be used in the authentication process. Other services require user to enter his login details in the API calls. Most use the API key approach.

.NET Support

Does .NET support the REST API? Sure! As long as REST web services are just collections of HTTP endpoints, we do not need to worry about accessing them from .NET since that the BCL offers us a bunch of classes (available in System.dll) that can help with HTTP requests and responses.

In addition, we will rely heavily on classes of System.Xml.dll to handle the data returned from functions (we will make use of functions that support XML.)

If we could write something in C# that calls our fake web function http://ab.c/api/shrink, we could end up with some code like this:

// C#

public void string Shorten(string url)
{
    string reqUri = @"http://ab.c/api/shrink?url=" + url;

    WebRequest req = WebRequest.Create(reqUri);
    req.Timeout = 5000;

    XmlDocument doc = new XmlDocument();
    doc.Load(req.GetResponse().GetResponseStream());

    return HandleXml(doc);
}

' VB.NET

Function Shorten(ByVal url As String) As String

    Dim reqUri As String = "http://ab.c/api/shrink?url=" & url

    Dim req As WebRequest = WebRequest.Create(reqUri)
    req.Timeout = 5000

    Dim doc As new XmlDocument()
    doc.Load(req.GetResponse().GetResponseStream())

    Return HandleXml(doc)

End Function

Encoding

If the URL to shorten have special characters like ‘&’, ‘?’, ‘#’, or ‘ ‘, those characters should be handled first before the URL is sent to the shortening function.

This special handling for URLs is usually called Percent-encoding or URL Encoding. This encoding replaces unsafe characters with their hexadecimal values preceded by percentage (‘%’) signs.

There are many unsafe characters that should be percent-encoded including ‘$’, ‘+’, ‘&’, ‘:’, and ‘=’. A nice discussion of URL Encoding can be found in the article URL Encoding by Brian Wilson.

Why unsafe characters are problematic? Consider the following example: we need to shorten the URL http://justlikeamagic.com/?s=twitter with our fake shortening service http://ab.c, we end up with a call to the function using the following address http://ab.c/api/shrink?url=http://justlikeamagic.com/?s=twitter. Now we have two ‘?’s!!!

So how can we encode URLs? Simply use the EscapeUriString() function of System.Net.Uri class it would work well for us here. If you need a full-featured encoder; a procedure that would work for all and every situation, you will need to consider creating one yourself, or you can use this:

// C#

char[] _chars = new char[]
{
     '%',
     '$' ,
     '&',
     '+',
     ',',
     '/',
     ':',
     ';',
     '=',
     '?',
     '@',
     ' ',
     '"',
     '',
     '#',
     '{',
     '}',
     '|',
     '\',
     '^',
     '~',
     '[',
     ']',
     ''', };

string EncodeUrl(string url)
{
    for (int i = 0; i < _chars.GetUpperBound(0); i++)
        url = url.Replace(
            _chars[i].ToString(),
            string.Format("{0:X}", (int)_chars[i]));

    return url;
}

string DecodeUrl(string url)
{
    for (int i = 0; i < _chars.GetUpperBound(0); i++)
        url = url.Replace(
            string.Format("{0:X}", (int)_chars[i]),
            _chars[i].ToString());

    return url;
}

' VB.NET

Private _chars() As String = _
{ _
"%", _
"$", _
"&", _
"+", _
",", _
"/", _
":", _
";", _
"=", _
"?", _
"@", _
" ", _
"", _
"”, _
“#”, _
“{“, _
“}”, _
“|”, _
“”, _
“^”, _
“~”, _
“[“, _
“]”, _
“‘”}

Public Function EncodeUrl(ByVal url As String) As String
For i As Integer = 0 To _chars.GetUpperBound(0) – 1
url = url.Replace( _
_chars(i).ToString(), _
String.Format(“{0:X}”, CInt(_chars(i))))
Next

Return url
End Function

Public Function DecodeUrl(ByVal url As String) As String
For i As Integer = 0 To _chars.GetUpperBound(0) – 1
url = url.Replace( _
String.Format(“{0:X}”, CInt(_chars(i))), _
_chars(i))
Next

Return url
End Function

Sample

Download the sample from here.

Where to Go Next

Now start with any shortening service you like (links are update regularly, new services will be available too):

• is.gd
• twurl.nl
• cli.gs
• bit.ly
• x.co
• 1click.at

Or else, check our URL Shortening Services tag.

Poll