API design for MyeBay, want to build it simple yet generic.

[akhil kapoor]

Hi,

I am in the process of writing RESTFul services that will power all containers on the MyeBay Dashboard(U'll know what this is if u're an eBay Buyer/Seller). These containers are something every ecommerce site will have in some form. To be specific they are basically container "Item", the most granular entity any ecommerce domain can have. The containers themselves are Scheduled(future listing scheduled by sellers), Sold, Unsold, ActiveListings and a few more... This probably is a vast sea and to keep things simple I will take en example one simple container, in this case the 'Scheduled' container.

Scheduled container is supposed to show items that are presently scheduled to be listed on the site by a seller. Each Item has a structure which contains its various attributes. To give you an example here is the XML fragment that represents an Item:

      <Item> ItemType

        <BuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </BuyItNowPrice>

        <eBayNotes> string </eBayNotes>

        <ItemID> ItemIDType (string) </ItemID>

        <ListingDetails> ListingDetailsType

          <ConvertedBuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedBuyItNowPrice>

          <ConvertedReservePrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedReservePrice>

          <ConvertedStartPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedStartPrice>

          <StartTime> dateTime </StartTime>

        </ListingDetails>

        <ListingDuration> token </ListingDuration>

        <ListingType> ListingTypeCodeType </ListingType>

        <PictureDetails> PictureDetailsType

          <GalleryURL> anyURI </GalleryURL>

        </PictureDetails>

        <PrivateNotes> string </PrivateNotes>

        <Quantity> int </Quantity>

        <QuantityAvailable> int </QuantityAvailable>

        <QuestionCount> long </QuestionCount>

        <ReservePrice currencyID="CurrencyCodeType"> AmountType (double) </ReservePrice>

        <SellerProfiles> SellerProfilesType

          <SellerPaymentProfile> SellerPaymentProfileType

            <PaymentProfileName> string </PaymentProfileName>

          </SellerPaymentProfile>

          <SellerReturnProfile> SellerReturnProfileType

            <ReturnProfileID> long </ReturnProfileID>

            <ReturnProfileName> string </ReturnProfileName>

          </SellerReturnProfile>

          <SellerShippingProfile> SellerShippingProfileType

            <ShippingProfileID> long </ShippingProfileID>

            <ShippingProfileName> string </ShippingProfileName>

          </SellerShippingProfile>

        </SellerProfiles>

        <SellingStatus> SellingStatusType

          <ConvertedCurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </ConvertedCurrentPrice>

          <CurrentPrice currencyID="CurrencyCodeType"> AmountType (double) </CurrentPrice>

          <QuantitySold> int </QuantitySold>

          <ReserveMet> boolean </ReserveMet>

        </SellingStatus>

        <ShippingDetails> ShippingDetailsType

          <GlobalShipping> boolean </GlobalShipping>

          <ShippingServiceOptions> ShippingServiceOptionsType

            <LocalPickup> boolean </LocalPickup>

            <ShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceCost>

            <ShippingSurcharge currencyID="CurrencyCodeType"> AmountType (double) </ShippingSurcharge>

          </ShippingServiceOptions>

          <!-- ... more ShippingServiceOptions nodes allowed here ... -->

          <ShippingType> ShippingTypeCodeType </ShippingType>

        </ShippingDetails>

        <ShippingPackageDetails> ShipPackageDetailsType

        </ShippingPackageDetails>

        <SKU> SKUType (string) </SKU>

        <StartPrice currencyID="CurrencyCodeType"> AmountType (double) </StartPrice>

        <TimeLeft> duration </TimeLeft>

        <Title> string </Title>

        <Variations> VariationsType

          <Variation> VariationType

            <PrivateNotes> string </PrivateNotes>

            <Quantity> int </Quantity>

            <SellingStatus> SellingStatusType

              <QuantitySold> int </QuantitySold>

            </SellingStatus>

            <SKU> SKUType (string) </SKU>

            <StartPrice currencyID="CurrencyCodeType"> AmountType (double) </StartPrice>

            <VariationSpecifics> NameValueListArrayType

              <NameValueList> NameValueListType

                <Name> string </Name>

                <Value> string </Value>

                <!-- ... more Value values allowed here ... -->

              </NameValueList>

              <!-- ... more NameValueList nodes allowed here ... -->

            </VariationSpecifics>

            <!-- ... more VariationSpecifics nodes allowed here ... -->

            <VariationTitle> string </VariationTitle>

            <WatchCount> long </WatchCount>

          </Variation>

          <!-- ... more Variation nodes allowed here ... -->

        </Variations>

        <WatchCount> long </WatchCount>

      </Item>

Currently there is an API which allows me to query for these items base on certain specific filters as follows:

ScheduledList

ScheduledList.Include 'true' if container itself needed in reponse. 'false' otehrwise

ScheduledList.IncludeNotes boolean

ScheduledList.Pagination PaginationType{EntriesPerPage, PageNo.}

ScheduledList.Pagination.EntriesPerPage int max:200 default:25

ScheduledList.Pagination.PageNumber int min:1 default:1

ScheduledList.Sort Asc/Desc, Asc Default analogous to  special filter.sort: StartTime, StartTimeDescending, Price, PriceDescending

But these filters are limited and this is not a REST style API, rather an old school style SOAP service that expects a simple request and gives back chunk of items based on the filters provided.

NOW, The real stuff. I am in the process of building a RESTFul API that will allow client to query for Scheduled Items in this case. I am planning to implement a model based on XPaths. each xpath being interpreted a a filter and the client given back a list of items filtered on that criteria.

to give you an example client could pass a request filter as a POST request like :

Filter Name                                                             Comparator                                              Value

item.shippingDetails.shippingServiceOptions              "equals"                                                   "Fedex"

Which will send back all items that qualify for shipping service options Fedex. 

I want to keep these filter names as generic as possible.

I would really appreciate if someone can critique on this approach and tell me how can I achieve a better design by making it a GET request rather than a POST and also if someone can come-up with a better design for this scenario, that'd be of great help.

Thanks

Akhil

[Repenning, Jack]

On May 16, 2013, at 5:38 PM, akhil kapoor <akhilka...@gmail.com> wrote:

I would really appreciate if someone can critique on this approach and tell me how can I achieve a better design by making it a GET request rather than a POST

How about this?

  GET /{container}/item?item.shippingDetails.shippingServiceOptions=Fedex

-- 

Jack Repenning

Repenni...@gmail.com

[akhil kapoor]

Thanks for the response. But what if I want to include multiple filters.

Lets say item.shippingDetails.shippingServiceOptions AND item.startTime. It could possible have 3 or four filter as well.

So for this case, is it adbised to use GET? or should I consider using POST?

Thanks