ql.io APIs for eBay Marketplaces

We are pleased to announce the release of eBay Marketplaces APIs based on ql.io:

https://github.com/ql-io/ql.io-ebay-mp-apis

We have created tables for most of the calls for the eBay Finding, Shopping, and Trading APIs. The fields required in the API calls are mapped using either EJS (Embedded JavaScript) or Mustache templates. You can use the tables as they are; or you can create your own tables and routes for the specific fields and calls that your application will need.

To use the tables that we have provided, clone the above repository. Then run

make clean install

You need to have the API key and authentication credentials for the particular API. You can get the API key at https://www.x.com/developers/ebay. Simply enter the appropriate values in the dev.json file in the config directory.

The test directory includes examples of various API calls. As described at http://ql.io/ we support different SQL-like statements – select, insert, delete, etc. We also support various HTTP verbs, such as GET, PUT, POST, and DELETE, with the SQL-like statements.

Usage scenarios

As examples of how the APIs can be used, here are three different scenarios. You can run each of the statements shown individually, and the call will return a “Success” message. Alternatively, you can use the UI to test if the calls have been successful.

SCENARIO 1:  WatchList add/remove (buyer’s perspective)

Here we use a keyword to search for items. For each item matching the keyword, we obtain the item ID and use it to add the item to the watchlist.

itemid = select searchResult.item[0].itemId from finding.findItemsByKeywords where keywords = 'camera';

insert into trading.AddToWatchList (ItemID) values ("{itemid");

We can also remove an item from the watchlist:

return delete from trading.RemoveFromWatchList where ItemID in ("{itemid");

SCENARIO 2:  AddItem + PlaceOffer (buyer’s + seller’s perspective)

This scenario uses the POST method with the AddItem call of the trading API. Here we pass the entire XML as the input string, which the ql.io engine will directly pass to the API gateway. This method is referred to as “passing opaque parameters” in the documentation at http://www.ql.io/docs/insert.

insert into trading.AddItem values ('<?xml version="1.0" encoding="utf-8"?>
   <AddItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <ErrorLanguage>en_US</ErrorLanguage>
      <WarningLevel>High</WarningLevel>
      <Item><Title>Best book</Title>
         <Description>This is the best book. Super condition!</Description>
         <PrimaryCategory>
            <CategoryID>377</CategoryID>
         </PrimaryCategory>
         <StartPrice>1.00</StartPrice>
         <ConditionID>3000</ConditionID>
         <CategoryMappingAllowed>true</CategoryMappingAllowed>
         <Country>US</Country>
         <Currency>USD</Currency>
         <DispatchTimeMax>3</DispatchTimeMax>
         <ListingDuration>Days_7</ListingDuration>
         <ListingType>Chinese</ListingType>
         <PaymentMethods>PayPal</PaymentMethods>
         <PayPalEmailAddress>magicalbookseller@yahoo.com</PayPalEmailAddress>
         <PictureDetails>
            <PictureURL>http://i.ebayimg.sandbox.ebay.com/00/s/MTAwMFg2NjA=/$(KGrHqJHJEsE-js(zPJ)BP)cWCLLSQ~~60_1.JPG?set_id=8800005007</PictureURL>
         </PictureDetails>
         <PostalCode>95125</PostalCode>
         <Quantity>1</Quantity>
         <ReturnPolicy>
            <ReturnsAcceptedOption>ReturnsAccepted</ReturnsAcceptedOption>
            <RefundOption>MoneyBack</RefundOption>
            <ReturnsWithinOption>Days_30</ReturnsWithinOption>
            <Description>
               If you are not satisfied, return the book for a refund.
            </Description>
            <ShippingCostPaidByOption>Buyer</ShippingCostPaidByOption>
         </ReturnPolicy>
         <ShippingDetails>
            <ShippingType>Flat</ShippingType>
            <ShippingServiceOptions>
               <ShippingServicePriority>1</ShippingServicePriority>
               <ShippingService>USPSMedia</ShippingService>
               <ShippingServiceCost>2.50</ShippingServiceCost>
            </ShippingServiceOptions>
         </ShippingDetails>
         <Site>US</Site>
      </Item>
      <RequesterCredentials>
         <Username>ql.io-test1</Username>
         <Password>ebay</Password>
      </RequesterCredentials>
      <WarningLevel>High</WarningLevel>
   </AddItemRequest>') ; 

return insert into trading.PlaceOffer (ErrorLanguage,EndUserIP,ItemID,Offer.Action, Offer.MaxBid, Offer.Quantity ) values ("en_US", "192.168.255.255", "200002581483", "Bid", "20.00","1"); 

The Item ID is obtained after the item is added. This Item ID can later be used to revise the item listing (such as to add to the item description).

SCENARIO 3:  SellingManagerProduct add/remove (seller’s perspective)

In this final example, we use Selling Manager product calls of the ql.io-based Trading API. Here, we use columns and name-value pairs (the first of the insert methods described in http://www.ql.io/docs/insert) to add a product:

result = insert into trading.AddSellingManagerProduct
         (Version,
          RequesterCredentials.eBayAuthToken,
          SellingManagerProductDetails.ProductName,
          SellingManagerProductDetails.QuantityAvailable,
          SellingManagerProductDetails.FolderID)
         values
         ("737",
          "MyAuthToken",
          "Harry Potter Book4",
          "50",
          "4651612545");

prodID = "{result.SellingManagerProductDetails.ProductID}";

And here, we delete a product:

return delete from trading.DeleteSellingManagerProduct where ProductID = "{prodID}";

Try it yourself!

Go ahead and fork https://github.com/ql-io/ql.io-ebay-mp-apis, and play with the tables and routes. For an overview and FAQs, see the readme. You can also ask questions and join the community discussion in the ql.io group.