I should firstly disclose that I'm a developer at 7digital, now let's get started. Firstly you'll need a 7digital API Key, sign up fill out the form and you should get it shortly.
Before we begin
You'll need Visual Studio 2010 / 2012 or Visual Studio Express Web Edition. We'll be relying on .Net 4.0 so be sure that you have that working (should be fine if you have vs2012).
You can find all the code for this walkthrough on GitHub
The Video (written walkthrough is below)
Step 1 - Create a new Web Project
File -> New -> Project -> Web -> Asp.Net MVC 4 Web Application
I'm going to call my Music Store 'Favourite Wedding Songs'
Step 2 - Got the Key, got the secret
Take the consumer key and consumer secret which you should hopefully have received by email and put them in your web.config
Step 3 - Install the 7digital API Wrapper from Nuget
Rather helpfully there's a 7digital API Wrapper on Nuget if we right click on references and click 'Manage Packages'. Then just search for 'sevendigital' you should find it and install away.
Step 4 - Creating an ApiUrl Class
Ok now before we dive in and create controllers and views for our web application we need a few basic bits of configuration code for our application. The 7digital API wrapper needs to know the API url which it expects to find by asking a class in a project which implements the IApiUrl interface. so I'd recommend creating a class much like that below. I'm hard-coding the urls in but obviously they're probably better off in config.
using SevenDigital.Api.Wrapper;
namespace FavouriteWeddingSongs.Models
{
public class ApiUri : IApiUri
{
public string Uri
{
get { return "http://api.7digital.com/1.2"; }
}
public string SecureUri
{
get { return "https://api.7digital.com/1.2"; }
}
}
}
Step 5 - Creating an OAuth Credentials
Remember how we put the Key and Secret in our web.config, well we need a class that exposes that config to the API Wrapper. As before it reflects over our code and looks for a class that implements the IOAuthCredentials interface. So as you can see in the code below we simply wrap up access to those settings stored in our web.config.
using System.Configuration;
using SevenDigital.Api.Wrapper;
namespace FavouriteWeddingSongs.Models
{
public class AppSettingsCredentials : IOAuthCredentials
{
public AppSettingsCredentials()
{
ConsumerKey = ConfigurationManager.AppSettings["Wrapper.ConsumerKey"];
ConsumerSecret = ConfigurationManager.AppSettings["Wrapper.ConsumerSecret"];
}
public string ConsumerKey { get; set; }
public string ConsumerSecret { get; set; }
}
}
Step 6 - Creating a MusicController and View
So this is where the real fun begins, so lets start by creating a MusicController that will have 2 action methods. The first will be the boring Index action which will initially do absolutely nothing but display an Index View, which will house a simple search box. When you click on Search we'll post (well actually GET) a SearchResults page which will take the search query and perform a TrackSearch using the 7digital API Wrapper. Below you'll find some simple example code for our MusicController.
using System.Web.Mvc;
using SevenDigital.Api.Schema.TrackEndpoint;
using SevenDigital.Api.Wrapper;
namespace FavouriteWeddingSongs.Controllers
{
public class MusicController : Controller
{
//
// GET: /Music/
public ActionResult Index()
{
return View();
}
[AcceptVerbs(HttpVerbs.Get)]
public ActionResult SearchResults(string q)
{
var results = Api<TrackSearch>
.Create
.WithQuery(q)
.WithParameter("imageSize", "200")
.Please();
return View(results);
}
}
}Right so ignore the Index() action for a second and look at the SearchResults(string q) action. Here we see the ApiWrapper in action, as you can see it gives us a really nice fluent interface where we specify the type of operation we want to perform. In this case it's a Api<TrackSearch> we .Create a request we give it a .WithQuery(q) q being the input parameter that comes from the form on the Index actions view. We use an optional parameter that lets us specify the width in pixels of the album art we want returned in the result set. Then finallly as many were taught by our parents we say .Please(); and the API Wrapper converts our query into a HTTP request to the 7digital track search endpoint. What it ultimately looks like will be something like,
http://api.7digital.com/1.2/track/search?q=Bruno Mars&oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2&imageSize=200
The above request will return a response in XML, which will look something like the example response in the track search documentation but handily for us the API Wrapper will deserialize this into a .Net type for us, We then just give the result set to our view to build our web page.
Step 7 - Building an amazing user experience
So firstly using Google as our inspiration we'll use the below code as our Index View.
@model dynamic
@{
Layout = null;
}
My Music Store
@using(@Html.BeginForm("SearchResults","Music",FormMethod.Get))
{
}Then we also need to work on the SearchResults. So have a look at the example below*
@model SevenDigital.Api.Schema.TrackEndpoint.TrackSearch @{ Layout = null; } Search Results@foreach (var item in Model.Results) {}@item.Track.Title
Your browser doesn't support the HTML5 audio tag. Buy this Track on 7digital for @item.Track.Price.FormattedPrice
*this is probably amongst the worst html ever, but you get the idea.
Note the track preview url. This can more formally be obtained using the preview api. But for our purposes this will probably suffice for now.
You'll also note that when this renders out our buy link will include you magic affiliateid on the end of the URL. This is the code that enables 7digital to track how many sales people you've referred have made.
Google would be proud of our extremely minimalist Index View.
Not so sure they'd like our results page, but we have used the funky html5 audio tag :)
Conclusion
We've barely scratched the surface of what is possible with the 7digital API so be sure to keep paying with the API and let us know what you come up with.
Thanks 7digital dev team.