Bora Demircan

1. Project Description

BuyShare.org is a social network platform that can share their consuming interests or any specific goals in life. The users can create friendlists, send message to each other, upload pictures and share with each other.

The purpose is to create a platform that will give information about products and brands, make presentation of the products and brands, encourage peoples’ consuming motives while giving people an entertaining social network environment. Another purpose is to make users share their goals in life with the goals pre posted by 43things.com members to be used as guide to buyshare.com members. In addition, buyshare.org is supposed to suggest products which are related to the goals that the users are interested.

The primary methods are as follows:

SendMessage(user_id): For users to send message to each other.
AddToFriendList(user_id): For users to add users to their friendlists.
ShowFriends(user_id): To list a specific users friendlist. Shows the name and thumbnail image of the friends listed.
UploadPhoto(): For users to upload photos.
ShowPhotos(user_id): To list the photos that a specific user has uploaded.
ListUsers(): For users to list the site members.
ShowUser(user_id): For users to show information about any user.
WriteTestimonial(user_id): Fot users to write testimonials to their friends.
GetProducts(query,category): For users to list the products from Yahoo Shopping Web Service.
CreateWishList(): For users to create wishlists in their preferences (i.e. Products I love, Products I hate, Things to take with you in summer etc.).
AddToWishList(product_id): For users to add products to their wishlists.
SendGift(friend_id, product_id): For users to send virtual gifts to each other among the products served by Yahoo Shopping Web Service.
WriteReview(): For users to write reviews about the products.
GetGoals(query): For users to search and list the goasl added by 43things.com members.
GetGoal(goal_id): For users to show goal information such as who thinks it is worth it or related goals or related products.
AddToMyGoals(goal_id): For users to add a specific goal the their goals (to do) list.
CommentGoal(goal_id): For users to comment on the goals.
ListInterested(id, type): For users to list the people who are interested in a specific product or goal. If the type variable is “product”, it lists the users interested in the product with the id. If the type variable is goal ”, it lists the users interested in the goal with the id.

2. Technical Design

2.1 Involved Web Services

2.1.1 Yahoo Shopping:
Yahoo Shopping is the service in which buyshare.org gets the product listings via “products search V2” and get Product Data via Catalog Listing

Yahoo Shopping Web Services is an external service in which all the information coming from the service is used to serve the members of the website. This service will be used in the project for having the users search for any product that they are insterested in and add these products to their wishlists or send virtual gifts to their friends.

2.1.1.1 Yahoo Shopping Processes:

Product Search V2:

Search for products with query

Request URL: http://api.shopping.yahoo.com/ShoppingService/V2/productSearch

Sample request URL: http://api.shopping.yahoo.com/ShoppingService/v2/productSearch?appid=YahooAppId&query=query_string&results=number_of_results&start=start_number

inputs:

NAME TYPE DESCRIPTION
appid string (required) The identification number of Yahoo API
query string (required if category is not specified) The query to search for
category string or integer (required if query is not specified) Specifies the category to be searched
results integer: 1-50 default value is 10 The number of results to return on a page
start integer: 1-300 default value is 1 The starting result position to return. The starting position cannot exceed 300

outputs:

Products Container for element Product. This is the top level element.
Contains each individual product offering. (list of Product elements). Each Product element contains either a Catalog or an Offer element, and has an attribute named type to indicate whether the enclosed element is a Catalog or an Offer element.
Attributes
totalResultsAvailable The number of query matches in the database
Elements Product

Product The Product Listed
Attributes
type It is the entry type (Offer or Catalog)
Elements Catalog If the Product type is Catalog, Offer If the Product type is Offer

Catalog It is the element of Product. If the Product type attribute is Catalog
Attributes
id Id of the catalog if type is Catalog
Elements ProductName, Thumbnail, ListImage

Offer It is the element of Product. If the Product type attribute is Offer
Attributes
id Id of the Offer if type is Offer
Elements ProductName, Thumbnail, ListImage

ProductName The name of the product
Thumbnail Contains an image described by Thumbnail elements. Its type is thumbnailType
ListImage The system use this if thumbnail is not available. It contains an image described by ListImage elements. Its type is thumbnailType

ListImage and Thumnail Elements Thumbnail and ListImage have the same types so their elements are the same which are URL, Height, Width

URL link to the image
Height The height of the image in pixels
Width The width of the image in pixels

Catalog Listing

Get detailed product details

Request URL: http://shopping.yahooapis.com/ShoppingService/V2/catalogListing

Sample Request URL: http://shopping.yahooapis.com/ShoppingService/v2/CatalogListing?appid=YahooAppId&
catalogid=Catalog_Idgetspec=1

inputs:

NAME TYPE DESCRIPTION
appid string (required) The identification number of Yahoo API
catalogid integer (required) The ID of the Yahoo! Shopping Buyers Guide catalog, as derived from a Catalog in a Product Search.
getspec 0 (default) or 1 When set to 1, returns specs (image, prices etc.) related to product identified by the given catalogid. I use to get the name and image url.

outputs:

Catalogs Top-level container for all responses.
Catalog Container for all elements (Offers, Reviews, Specs) related to a Catalog.This is a top level element
Attributes
id The id of the catalog
Elements Specs

Specs Container enclosing all specifications returned for the product. Returned only if getspec is specified in the request with value set to 1 and there are available Specs to return.
Elements ProductName, Thumbnail

ProductName Title of the product
Thumbnail The URL of a product’s thumbnail image and its height and width in pixels. It is specified with the ImageType
Elements URL, Height, Width

URL link to the image
Height The height of the image in pixels
Width The width of the image in pixels

2.1.2.2 XSD Documents for Yahoo Shopping API:

Product Search V2

The Yahoo! Shopping Product Search REST response conforms to XML 1.0. The schema document for this response is located at http://api.shopping.yahoo.com/shoppingservice/v2/productsearch.xsd

An XSD document for Product Search V2 needed to provide the data to serve the buyshare.org would be something like below:

<xs:schema targetNamespace=”urn:yahoo:prods” elementFormDefault=”qualified”>

<xs:element name=”ProductSearch”>

<xs:complexType>

<xs:sequence>

<xs:element name=”Products” type=”ProductsType”/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:complexType name=”ProductsType”>

<xs:sequence>

<xs:element name=”Product” type=”ProductType” minOccurs=”0″ maxOccurs=”300″/>

</xs:sequence>

<xs:attribute name=”totalResultsAvailable” type=”xs:nonNegativeInteger” use=”optional”/>

</xs:complexType>

<xs:complexType name=”ProductType”>

<xs:choice>

<xs:element name=”Catalog” type=”CatalogType”/>

<xs:element name=”Offer” type=”OfferType”/>

</xs:choice>

<xs:attribute name=”type” type=”xs:string” use=”required”/>

</xs:complexType>

<xs:complexType name=”CatalogType”>

<xs:sequence>

<xs:element name=”ProductName” type=”xs:string”/>

<xs:element name=”Thumbnail” type=”ThumbnailType” minOccurs=”0″/>

<xs:element name=”ListImage” type=”ThumbnailType” minOccurs=”0″/>

</xs:sequence>

<xs:attribute name=”id” type=”xs:nonNegativeInteger” use=”required”/>

</xs:complexType>

<xs:complexType name=”OfferType”>

<xs:sequence>

<xs:element name=”ProductName” type=”xs:string”/>

<xs:element name=”Thumbnail” type=”ThumbnailType” minOccurs=”0″/>

<xs:element name=”ListImage” type=”ThumbnailType” minOccurs=”0″/>

</xs:sequence>

<xs:attribute name=”id” type=”xs:string” use=”optional”/>

</xs:complexType>

<xs:complexType name=”ThumbnailType”>

<xs:sequence>

<xs:element name=”Url” type=”xs:string”/>

<xs:element name=”Height” type=”xs:nonNegativeInteger”/>

<xs:element name=”Width” type=”xs:nonNegativeInteger”/>

</xs:sequence>

</xs:complexType>

</xs:schema>

Catalog Listing

The schema document for this service response is located at http://shopping.yahooapis.com/shoppingservice/v2/cataloglisting.xsd

An XSD document for Catalog Listing needed to provide the data to serve the buyshare.org would something like below:

<xs:schema targetNamespace=”urn:yahoo:merchoffers” elementFormDefault=”qualified”>

<xs:element name=”Catalogs”>

<xs:complexType>

<xs:sequence>

<xs:element name=”Catalog” type=”CatalogType” minOccurs=”0″ maxOccurs=”5″/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:complexType name=”CatalogType”>

<xs:sequence>

<xs:element name=”Specs” type=”SpecsType” minOccurs=”0″ maxOccurs=”1″/>

</xs:sequence>

<xs:attribute name=”ID” type=”xs:integer” use=”required”/>

</xs:complexType>

<xs:complexType name=”SpecsType”>

<xs:sequence>

<xs:element name=”Thumbnail” type=”ImageType” minOccurs=”0″/>

<xs:element name=”ProductName” type=”xs:string”/>

</xs:sequence>

</xs:complexType>

<xs:complexType name=”ImageType”>

<xs:sequence>

<xs:element name=”Url” type=”xs:string”/>

<xs:element name=”Height” type=”xs:nonNegativeInteger”/>

<xs:element name=”Width” type=”xs:nonNegativeInteger”/>

</xs:sequence>

</xs:complexType>

</xs:schema>

2.1.2 43things.com:
43things.com is an external web service in which buyshare.org gets the goals of people via “search goal method” from the request URL http://www.43things.com/service/search_goals

By the help of this service, the collected neccessary information coming from 43things.com will be available to the users to search for any included goal that they are insterested in and add to their goalslists or share these goals with their friends.

43things.com is being used as an internal service while getting the related products about a specific goal. The system sends the output coming from get_goal_by_id method to Yahoo Shopping Web Service and gets the related products about that goal.

2.1.2.1 43things.com Processes:

search_goals
Search for goal names based on the q* parameter which is the query parameter:

Sample Request URL:
http://www.43things.com/service/search_goals?api_key=api_keyq=query&offset=offset&max=max

inputs:

NAME TYPE DESCRIPTION
api_key string (required) - identification number of 43thing.com API
q string (required) - The query to search for
offset integer: - default value is 10 The starting result position to return
results integer: - default value is 20 and can’t be higher than 20 The maximum number of results to return on a page

outputs:

Title - The title string: “Goal search results for “query” on 43 Things”. This is a top level element
Query - The query posted. This is a top level element
Pagination - The pagination data. This is a top level element
Elements Offset, Max, Total, Next_offset, Previous_offset
Goal - Goal top level element

Attributes
Goal_id The id number of the goal
Elements Name, Num_registered_people
Offset The starting result position to return
Max The maximum number of results to return on a page
Total Total results returned in query
Next_Offset The starting position of the next page
Previous_Offset The starting position of the previous page
Name The name of the goal
Num_registered_People number of people who are registered to the goal in 43things.com

get_goal_by_id
Retrieve information for a particular goal, by its id

inputs:

NAME TYPE DESCRIPTION
api_key string (required) identification number of 43thing.com API
id int (required) Id of the goal

outputs:

Goal This is the document element
Atrributes
Goal_id The identification of the goal
Elements Name, Num_registered_people, Worth_it_data, Tags

Name The name of the goal. This is a top level element
Num_registered_people The number of registeres people to the goal in 43things.com. This is a top level element
Worth_it_data The data that is stored to determined who thinks that the goal is worth it. This is a top level element
Elements Num_say_worth_it, Num_say_not_worth_it, Percentage_worth_it

Tags Related tags according to the goal. This is a top level element
Elements Tag

Num_say_worth_it Number of people who thinks the goal is worth
Num_say_not_worth_it Number of people who thinks the goal is not worth
Percentage_worth_it The percentage of the people who thinks the goal is worth among who have voted

Tag One specific tag element related to the goal element

2.1.2.2 XSD Documents for 43things.com API:

34things.com does not use any schema document linked to the response XML files.

An XSD document for search_goals method of 43things.Com needed to provide the data to serve the buyshare.org would be something like below:

search_goals

<xs:schema targetNamespace=”urn:43things:prods” elementFormDefault=”qualified”>

<xs:element name=”feed”>

<xs:complexType>

<xs:sequence>

<xs:element name=”title” type=”xs:string”/>

<xs:element name=”query” type=”xs:string”/>

<xs:element name=”pagination” type=”PaginationType”/>

<xs:element name=”goal” type=”GoalType”/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:complexType name=”PaginationType”>

<xs:sequence>

<xs:element name=”offset” type=”xs:nonNegativeInteger” default=”0″/>

<xs:element name=”max” type=”xs:nonNegativeInteger” default=”20″ maxOccurs=”20″/>

<xs:element name=”total” type=”xs:nonNegativeInteger”/>

<xs:element name=”next_offset” type=”xs:nonNegativeInteger”/>

<xs:element name=”previous_offset” type=”xs:nonNegativeInteger”/>

</xs:sequence>

</xs:complexType>

<xs:complexType name=”GoalType”>

<xs:sequence>

<xs:element name=”name” type=”xs:string”/>

<xs:element name=”num_registered_people” type=”xs:nonNegativeInteger”/>

</xs:sequence>

<xs:attribute name=”id” type=”xs:nonNegativeInteger” use=”optional”/>

</xs:complexType>

</xs:schema>

get_goal_by_id

An XSD document for get_goal_by_id method of 43things.Com needed to provide the data to serve the buyshare.org would be something like below:

<xs:schema targetNamespace=”urn:43things:prods” elementFormDefault=”qualified”>

<xs:element name=”goal”>

<xs:complexType>

<xs:sequence>

<xs:element name=”name”/>

<xs:element name=”worth_it_data” type=”WorthType”/>

</xs:sequence>

<xs:attribute name=”goal_id” type=”xs:nonNegativeInteger” use=”optional”/>

</xs:complexType>

</xs:element>

<xs:complexType name=”WorthType”>

<xs:sequence>

<xs:element name=”num_say_worth_it” type=”xs:nonNegativeInteger”/>

<xs:element name=”num_say_not_worth_it” type=”xs:nonNegativeInteger”/>

<xs:element name=”percentage_worth_it” type=”xs:nonNegativeInteger”/>

</xs:sequence>

</xs:complexType>

</xs:schema>

2.2 Workflow

Users are able to search and list Yahoo Products and add to their wishlist or send gifts to their friends. As shown in Figure 1 when a user requests a product list according to the query and/or the category of the product, buyshare.org sends a web service request to Yahoo Shopping API, then parses the coming results and shows on the users browser.

When the user wants to add a specific product to his/her wishlist, the system gets the product id of the listed product and sends it to the Products Controller. Products Controller sends the product id to Yahoo Shopping Catalog Listing API, gets the necessary product data and stores the product name and thumbnail url to the database with a new unique id. By getting the unique id from the newly stored product, it stores the product to the users wishlist with its new id and shows the info that the product is added to the wishlist on users browser.

When a user wants to send a virtual gift to a friend, he/she chooses his friend from a dropdown menu of the friendlist. The system gets the friends id and the product id and sends it to the Gifts Controller. Gifts Controller sends the product id to Yahoo Shopping Catalog Listing API, gets the necessary product data and stores the product name and thumbnail url to the database with a new unique id. By getting the unique id from the newly stored product with pre obtained friend id it stores the product and the friend_id to the users giftlist with its new id and shows the info that the gift is sent to the friend on users browser.

Whenever a new product is added to the database, system administrators are being notified. Here I have used WS notification specification. The ProductListener listen to new additions of products to database and sends necessary information to the system administrator. Since a users has the admin priviledges, he/she is automatically subscribed to the notification.

As shown in Figure 2, users can also list goals stored in 43things.com and add these goals to their goals lists. The data will be coming from 43things.com Web Services. Users can also show specific information about specific goals. In the goal profile page, they will view the information on how many people thinks that the goal is worth it or not and the percentage of the worth it data. In addition, related goals and related products will be listed on the page. The related products will be coming from Yahoo Shopping Product Search V2 Web Service which will count as an internal service.

When a user wants to add a goal to his/her goal list, the system will automatically store the goal information in the database to the goalslist table. The goal will also be a added to the goals list of the user.

Figure 1 - Yahoo Shopping API Sequence Diagram

Figure 2 - 43Things.com API UML Sequence Diagram

No Comments