Adding the 30 Boxes API to your website with WebMatrix

Using 30 Boxes is one of the easiest ways to share your Calendar online. With the 30 Boxes API, you can share your Calendar events on your personal website. This article will show how to quickly add your 30 Boxes events using their REST API.

Create a website with WebMatrix

In this article, we will be using WebMatrix. WebMatrix is a free tool that allows you to create, customize, and publish webpages. It gives a number of different ways that you can create websites. One of the features is providing existing open sources applications such as WordPress, Joomla, DotNetNuke or Umbraco. WebMatrix can be downloaded for free at microsoft.com/Web/WebMatrix .

If you need help downloading and installing WebMatrix, it may be a good idea to read Getting Started with WebMatrix. The article provides step by step instructions on installing WebMatrix

After WebMatrix is finished installing, open it. Click "Site from Template" on the WebMatrix welcome screen.

For this example we will use is an Empty Site template. This template is a full-featured HTML5 site. Click Empty site and hit ok.

Clicking ok will take you to your WebMatrix workspace. This contains information about your local host as well a provides resources on developing your site.

You’ll notice that WebMatrix allows you to move between different workspaces by selecting the buttons on the left hand side. At present the Site button is selected which gives you details on your web site, such as the URL of the site, and other tools that you can use such as monitoring your site requests. You can look into this workspaces as you work but for this article, we will be working with our Files workspace. To get to your Files workspace, click the "Files" tab on the lower left hand of WebMatrix.

Once in your Files workspace you can see all your files. Since we choose an Empty Site, we do not have any files for our website yet.

Let's create a new webpage for our application. Click "new" on the menu ribbon.

This will cause a box to appear with all the different file types you can choose. Choose an .csHTML file and give it a name.

We now have an HTML5 valid, empty website. Let's get started adding our 30 Boxes events.

Add your 30 Boxes API

The 30 Boxes API website contains all the steps and information needed in order to get started using the 30 Boxes API.

To use the 30 Boxes API, we need an API key. Before we can get an API key, we need to sign in or create an account with 30 Boxes. If you don't already have an account with 30 Boxes, visit the 30 Boxes Sign Up page to get started creating an account or click the "sign up" link in the top right corner.

You will be asked to provide an email address, a password, and first and last name. Click the "sign up" button when you're done filling in the form.

When you've submitted for account info you will receive a message notifying you that a confirmation email was sent to the email you provided.

To get your account activated, you must check your email and follow the link given to you.

Following the link will take you back to 30 Boxes where you can add additional account information. This is in 4 steps. The first step will ask to include your Facebook, Flickr, MySpace, and other social media information. Remember, this is not required and you may skip the wizard at any time.

Step 2 will ask you to choose your time zone and to enter some of your contact's birthday information.

Step 3 asks if you wish to include some of your friends. You can do this now or later.

Step 4 is simply different options you have for getting started using 30 Boxes.

At the bottom of the page is a "get started" link.

You will be taken to your 30 Boxes calendar. Here you can add events. You can type a new event in the "add new event here..." box.

You can also add an event to a specific day. This will cause a pop up box to appear where you can add the event.

You can also edit existing events if you wish to include more information about it.

Clicking on a specific day of your calendar will show a pop up box with the events for that day.

That was just a quick overview on adding and managing your events with 30 Boxes. Let's now get started on adding the 30 Boxes API to our website.

Get your API Key

Head back to the 30 Box API website to get your API key. Click the "get your API key" link on this page.

You will be given an API key.

The 30 Boxes API uses a REST format. This means that your webpage will make a request and you will receive a response with the information you requested. You can then do something with the requested information on your webpage. 30 Boxes provides an example of the general format of the 30 Boxes API request.

The 30 Boxes API provides numerous different methods. These are listed farther down on the 30 Boxes API page.

Even farther down the page, the API methods are explained. Included is the required and optional parameters for the web request.

You may have noticed that the example for each method includes the actual web request (meaning your API key is placed in the example for you). This means you can simply copy and paste each "example" of a method and have it be a valid API web request for you. In this article, we will only look at 1 method since to use the different method, you would simply have to change the method name in your web request.

Add the API Web Request

The API method we will be using in this example is the events.Get method. This method requires 2 arguments (api key & authorized user token) and 2 optional arguments (start and end date). The authorized user token is generated for you so all we simply have to do and copy the method example.

Head back to the empty webpage you made earlier in WebMatrix. Remember we made a .cshtml file instead of a regular .html file. A .cshtml file is a new, special file type for WebMatrix. This type of file can contain the usual contents of a webpage including HTML and JavaScript code but, what sets it apart from a regular .html file is that it can also contain code for programming webpages. .cshtml files let you embed ASP.NET code into your HTML page using the new Razor syntax (which is most commonly denoted using @ - similar to PHP's $).

Razor code can go anywhere on your webpage. Blocks of code (written between @{ }), single line statements, and even single variables can be put anywhere, just make sure you have the correct syntax! If you want a more in-depth introduction to WebMatrix, you can find numerous resources on the subject including the asp.net website.

This article will simply show you have to use Razor code to make REST (Representational State Transfer) requests and responses using the 30 Boxes API. The basic idea of a REST request is that a request is sent to a special URL including some information. It could be information that was inputted into a webform or just a few simple variables. A response is then received containing the server's response (in an XML document). This received XML document can then be parsed to extract the desired information and further actions can be taken.

For this example, we will make the request to get our 30 Boxes events and will then display these events on our personal webpage.Let's make a list of the steps we must do to achieve this.

  1. Make Web Request
  2. Get Web Response in form of XML document
  3. Parse our received XML document
  4. Display our desired information on our webpage

Sound pretty simple right? Once you get the hang of HTTP requests and responses, you can essentially use any REST APIs!

Before we get started on our request and response, let's create the code where we will display our received information. In the <body> of our page, let's add some structure to our page. Add the following code:

<div id="container">
    <h1>Welcome to My WebSite</h1>
    <h3>My Events</h3>
    <div id="events">

    </div>
    <hr/>
    <p>These events are found in my calendar at <a href="http://30boxes.com">30 Boxes</a></p>
</div>

We can also add some CSS to make our page pretty! Note that this is not required. Create a new .css file and add the following code:

body {
    background-color: #5F9EA0;
}

#container {
    font-family: palatino linotype; 
    width: 80%;
    margin-left: 18% ;    
    padding: 10px;
    margin-top: 25px;
    background-color: White;
}

h1 {
    font-size: 42px;
    text-align: center;
}

h3 {
    text-align: center;
    font-size:30px;
    
}
#events {
    border: 1px solid black; 
    padding: 15px; 
    width: 400px;
    margin-left: 26%;
    display: block;
}

.name a:link {
    background-color: #BFD8D9;
    color:Black;
    display: block;
    text-decoration: none;
    padding:5px;
    margin-bottom: -15px;
}

.name a:hover {
    background-color: black;
    color: #BFD8D9;
}

.dates {
    margin-top: -25px;
    }
    
    .dates a:link{
    background-color: #D2E4E4;
    color: Black;
    display: block;
    text-decoration: none;
    padding:5px;
}

.dates a:hover {
    background-color: black;
    color: #D2E4E4;
}

We now need to link our external stylesheet to our webpage. Add to the <head> of your page:

<link rel="stylesheet" href="style.css" type="text/css"/>

Let's run our page just to see how it looks. Click the "run" button on the menu ribbon. Your page should look similar to this, depending on if you applied CSS to it.

Notice that we have a blank <div> waiting for content. This is where we will place the information we receive from our web request. Let's add that request right now. Add the following code to the top of your .cshtml file, BEFORE the <!DOCTYPE html> tag.

@{                 
   string uri = "http://30boxes.com/api/api.php?method=events.Get&apiKey=yourapiKey&authorizedUserToken=yourtoken";
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);     
    WebResponse response = request.GetResponse();
    Stream strm = response.GetResponseStream();
    XmlTextReader reader = new XmlTextReader(strm);
}

Make sure you replace "yourapiKey" with your actual API key and "yourtoken" with your authorized user token. Remember earlier when it was noted that the 30 Boxes API page actually generated the method requests for you? You can simply copy this example request and set it to be the value of our string variable "uri"

Let's go this code. First, we save our request into a variable called "uri." We then make a HTTPWebRequest using this variable. Next, we get a WebResponse from our web request. Then, we a response stream. Lastly, we create a XMLTextReader object. The XMLTextReader object can be used to parse through our received XML document to retrieve our desired information.

That was a simple way to make a web response and request. But, in order for it to work, we must include some extensions. Add before our code:

@using System.Xml;
@using System.IO;
@using System.Text;

This code MUST be placed before any Razor code in order to not receive a compilation error.

We can now parse our received XML document. The XML document we received in our web response looks similar to this:

<?xml version="1.0" encoding="utf-8"?>
<rsp stat="ok">
<eventList><userId>47</userId><listStart>2011-02-01</listStart><listEnd>2011-05-02</listEnd>
<event><id>6222</id>
<summary>Susan&#039;s Birthday</summary>
<notes></notes>
<start>2006-03-03 00:00:00</start>
<end>2006-03-03 00:00:00</end>
<lastUpdate>2005-12-19 13:19:31</lastUpdate>
<allDayEvent>1</allDayEvent>
<repeatType>yearly</repeatType>
<repeatEndDate>0000-00-00</repeatEndDate>
<repeatSkipDates></repeatSkipDates>
<repeatICal>
RRULE:FREQ=YEARLY;INTERVAL=1</repeatICal>
<reminder>-1</reminder>
<tags></tags>
<externalUID></externalUID>
<privacy>shared</privacy>
<invitation>
<isInvitation>0</isInvitation></invitation>
</event>
<event><id>6215</id>
<summary>Jim&#039;s Birthday</summary>
<notes></notes>
<start>2006-02-19 00:00:00</start>
<end>2006-02-19 00:00:00</end>
<lastUpdate>2005-12-19 13:08:29</lastUpdate>
<allDayEvent>1</allDayEvent>
<repeatType>yearly</repeatType>
<repeatEndDate>0000-00-00</repeatEndDate>
<repeatSkipDates></repeatSkipDates>
<repeatICal>
RRULE:FREQ=YEARLY;INTERVAL=1</repeatICal>
<reminder>-1</reminder>
<tags></tags>
<externalUID></externalUID>
<privacy>shared</privacy>
<invitation>
<isInvitation>0</isInvitation></invitation>
</event>
</eventList>

If we know the name of the XML tags that we wish to display on our page, we can simply parse through the response and print out the tags' value on our page. For this example, we want to display the summary of the events and the start date of the event. Let's now add the code that will do this.

Remember the empty <div> we added to our page earlier? Let's add our Razor code here. Add this code between <div id="events"> and </div>:

@{  
    while (reader.Read()){
        if( reader.Name == "summary") {
            var summary = reader.ReadString();
            <p class="name"><a href="#"><b>Event:</b> @summary</a><br /></p>
        }
        if (reader.Name == "start") {
            var starts = reader.ReadString();
            <p class="dates"><a href="#"><b>Date:</b> @starts</a></p>
        }
    }
    response.Close();
}   

This code is a perfect example of flexibility of the Razor language. It can be put anywhere on the page and you can incorporate HTML into it!

Let's break this code down. We use a while loop to read through the whole XML document (with our XMLTextReader that we created earlier). We then check if the current XML tag we are on is equal to either of the tags we want to display on our page (summary and start date). If it is, we then put the value of the tag into a variable and then use HTML to print the tag's value onto our webpage. Once we leave the while loop (we're done reading our XML document) we then close our response stream.

Let's run our page to see our events displayed on it.

If you added the CSS stylesheet from earlier, hovering over an event will cause the color to change.

This was just one example of how you can use 30 Boxes API. To change your web request, you simply have to change the variable "uri" value to equal one of the method examples found on the 30 Boxes api website.

Additional Resources

Download WebMatrix http://www.microsoft.com/web/webmatrix/

Learn how to Download and Install WebMatrix http://www.microsoft.com/web/post/web-development-101-part-1-getting-started-with-webmatrix

Learn more http://www.microsoft.com/web/post/Web-Development-101-using-WebMatrix

Create a website with a WebMatrix site template http://www.microsoft.com/web/post/create-a-website-from-a-webmatrix-site-template

Publish your website http://www.microsoft.com/web/post/how-to-publish-a-web-application-using-webmatrix

Learn to download, edit and republish your website http://www.microsoft.com/web/post/download-edit-and-republish-your-website-with-webmatrix

You can discuss this article using the adjacent Facebook talkback.

For technical questions please visit our discussion forums, where we have a vibrant community of developers like you, as well as Microsoft engineers who are ready to answer your questions!