tools4etsy

Step 1

We need to create a new project and reference both the EtsyCACHE & EtsyNET libraries.

Step 2

Next we need to create a class to give the project global access to the EtsyCACHE library. I normally call this class MyEtsyCache.vb to the App_Code folder and inset the following code:

            Public Class MyEtsyCache

                Public Shared WithEvents Etsy As New EtsyCache.EtsyCache()
                Public Shared ApiCallCount As Integer

                Shared Sub New()
                    Etsy.PageSize = 30
                End Sub

                Private Shared Sub Etsy_onAPICall(ByVal URL As String) Handles Etsy.onAPICall
                    ApiCallCount += 1
                End Sub

            End Class
            

Step 3

To make MyEtsyCache.vb accessable project wide and also indirectly initialize the EtsyNET library through the EtsyCACHE library, we add Global.asax file to the project and insert the following code:

            Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
                ' Code that runs on application startup

                MyEtsyCache.Etsy.PageSize = 48  '!!! number of records to be retrieved each API call...
                                                '    default pagesize is 10 records per API call 
                                                '    as per ETSY documentation 
                                                '    @ developer.etsy.com/docs 
                MyEtsyCache.Etsy.ApiKey = "xxxxxxxxxxxxxxxxxxxxxxxx"    '<-- API KEY HERE!!!!!!

            End Sub
            

If you don't have an ETSY API key, then goto Etsy Developer Community Application Registration and obtain one.

Step 4

Ok. Now we're ready to build the search page. When you create a new website project, Visual Studio adds a Default.aspx page. For the purpose of this tutorial we'll work with this page.

The page will have two parts to it:

1. Search
2. Resultset

First thing, we need to add the search facility. So we need to add a label, textbox, and a button to the client .aspx page code:

                <h1>getFavoriteListingsOfUser Example Code</h1>
                <asp:Label ID="Label1" runat="server" Text="Enter Shop name: " AssociatedControlID="TextBox1"></asp:Label>
                <asp:TextBox ID="TextBox1" runat="server" Text="" CssClass="search" ></asp:TextBox>
                <asp:Button ID="Button1" runat="server" Text="Search" CssClass="search" />
            

Next we need to add a ListView, DataPager, and ObjectDataSource to handle the postback search and display any results if found:

                <asp:ListView ID="lvListings" runat="server" DataSourceID="dsListings">
                    <LayoutTemplate>
                        <div id="items" >
                            <div id="itemPlaceholder" runat="server" />
                        </div>

                        <div class="pagerbar">
                            <div class="pageritems">
                                <asp:DataPager ID="DataPager2" runat="server" PageSize="12">
                                    <Fields>
                                        <asp:NextPreviousPagerField ButtonType="Link" 
                                                            ShowFirstPageButton="true" 
                                                            ShowPreviousPageButton="false" 
                                                            ShowNextPageButton="false" 
                                                            ShowLastPageButton="false" 
                                                            ButtonCssClass="dpbut" />
                                        <asp:NumericPagerField ButtonCount="9" 
                                                            RenderNonBreakingSpacesBetweenControls="true" 
                                                            ButtonType="Link" 
                                                            NumericButtonCssClass="dpbut" 
                                                            NextPreviousButtonCssClass="dpbut" 
                                                            CurrentPageLabelCssClass="dpbut" />
                                        <asp:NextPreviousPagerField ButtonType="Link" 
                                                            ShowFirstPageButton="false" 
                                                            ShowPreviousPageButton="false" 
                                                            ShowNextPageButton="false" 
                                                            ShowLastPageButton="true" 
                                                            ButtonCssClass="dpbut" />
                                    </Fields>
                                </asp:DataPager>
                            </div>
                        </div>

                     </LayoutTemplate>
                    <ItemTemplate>
                        <div class="item">
	                        <a href="http://www.etsy.com/view_listing.php?listing_id=<%# Eval("ListingID") %>" 
	                              title="<%# Eval("Title")%>" 
	                              rel="<%# Eval("Title")%>">
	                            <asp:Image ID="Image1" 
	                                          class="photo" 
	                                          runat="server" 
	                                          ImageUrl='<%# Eval("ImageURL155x125") %>' />
	                            <asp:Label id="Label1" 
	                                          class="desc" 
	                                          runat="server"><%#Eval("Title")%></asp:Label>
	                        </a>
                                <div class="seller">
                                    <a href="http://www.etsy.com/shop.php?user_id=<%# Eval("UserID") %>" 
                                          title="Check out <%# Eval("UserName")%>'s store on www.etsy.com"><%#Eval("UserName")%></a>
                                </div>
                                <div class="price"><span>US$</span>
                                    <asp:Label ID="Label2" 
                                                  runat="server"><%#Eval("Price")%></asp:Label>
                                </div>
                        </div>
                    </ItemTemplate>
                    <EmptyDataTemplate>
                        <div id="items">
                            <div>
                                <span>It appears that ETSY has no listings currently for the selected</span>
                            </div>
                        </div>
                    </EmptyDataTemplate>
                </asp:ListView>

                <asp:ObjectDataSource ID="dsListings" runat="server" 
                            EnableCaching="True" CacheDuration="300"
                            OldValuesParameterFormatString="original_{0}" SelectMethod="getItems" 
                            TypeName="EtsyCache.ListingsDB">
                    <SelectParameters>
                        <asp:Parameter DefaultValue="3" 
                                       Name="CallType" 
                                       Type="Object" />
                        <asp:SessionParameter DefaultValue="" Name="SearchID" SessionField="ID" 
                            Type="String" />
                        <asp:Parameter DefaultValue="0" 
                                       Name="SortOrder" 
                                       Type="Object" />
                    </SelectParameters>
                </asp:ObjectDataSource>
            

Lets break this piece of code down:

1. The DataPager control has the PageSize property set to 12. In the Global.asax above we set the PageSize property to 48. Why have we done this? The answer is simple - We're retrieving 4 pages of display data at a time. This reduces the number of round trips being made and giving the user a more responsive interface.
2. The ObjectDataSource points to the EtsyCACHE DB access class for Listings ListingsDB and passes in the search data. The getItems function has the DataObjectMethod attribute set so that when you use the ObjectDataSource wizard, it's straight forward to select.
3. For the EtsyCACHE library to remember the search results we need to tell the ObjectDataSource to enable Caching by flagging the EnableCaching property and setting the CacheDuration property to how long we want to cache the search results - 300 seconds / 5 minutes in this tutorial.
4. As the user pages throught the results, the EtsyCACHE library remembers what data it's already retrieved and only calls etsy if the user requests data that the EtsyCACHE library hasn't already retrieved. If the CacheDuration expires, ASP.NET automatically recycles the memory and the EtsyCACHE library will see this and start the retrieval process all over again.
5. A nice side benefit of the EtsyCACHE library is that the data is global at application level. What this means is that the cached data is accessable to all visitors who use your webite. Pretty cool huh?

To show how the EtsyCACHE library reduces the number of API calls made to Etsy, we will add a label that server-side code can publish the number of API calls used. Inset the following code before the ListView control.

                <p><span>API Count: </span><asp:Label ID="labAPICount" runat="server" Text="0" /></p>
            

Step 5

Ok, we're two-thirds of the way there. Next we need to set up some server-side code to handle the Button click postback. We need to reset the DataPager page position and set the search data against a Session variable (in a production website you would use a QueryString so that the visitor could bookmark the search).

                Protected Sub Button1_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles Button1.Click
                    Dim dp As DataPager = CType(lvListings.FindControl("DataPager2"), DataPager)
                    If dp IsNot Nothing Then
                        dp.SetPageProperties(0, dp.PageSize, True)
                    End If
                    Session("ID") = TextBox1.Text
                End Sub
            

Lastly, we need to wire up the API Count client-side Label control to display the number of calls made.

                '-- Report Global API Count
                '
                Protected Sub Page_PreRenderComplete(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.PreRenderComplete
                    labAPICount.Text = MyEtsyCache.ApiCallCount.ToString
                End Sub
            

And that's it! Fire up the code and try searching 'spunkyarn' (or your own Etsy user name) for example; paging through the results and note the API count and responsiveness.

Wrapping up, the tutorial has demonstrated how to work with Etsy's RESTful API without writing a single line of code to manage the calling and paging through the data - all achieved through the EtsyCACHE library.

We hope that this tutorial's been useful. We'd love to hear of your experiences with the Libraries provided and if you develop an application or website, please let us know by leaving us feedback / suggestions / comments and we hope that you'll give the Libraries credit.

Happy Coding!