Retrieving Attribute and Product Meta-Data

This chapter describes how to retrieve and refresh meta-data related to Item Specifics and Pre-filled Item Information. Before reading this chapter, you should be familiar with the concepts and workflows described in Working with Attribute-Based Features.

eBay users list in thousands of categories worldwide. Many of these categories support Item Specifics, and more support is being added each month. Support for Pre-filled Item Information is also expected to grow over time. In addition, as the needs of the eBay community change, the existing Item Specifics meta-data for a given category may also need to change.

For example, eBay can change characteristic set mappings for a given category in these ways:

Add (map) a category to or remove (unmap) a category from a characteristic set
Modify a category-to-characteristic set mapping

Similarly, eBay may update a given characteristic set's attributes and values in a number of ways:

Make an optional attribute required (or a required attribute optional)
Add a new optional or required attribute or remove an attribute
Add a new value to or remove a value from an attribute
Change an attribute's data type (e.g., string to number)
Change the dependency relationships between two attributes
Change an attribute's validation rules (such as a regular expression rule)

In addition, eBay may add or modify elements in the schema to accommodate new kinds of meta-data.

All these kinds of changes mean you should expect to update your application's locally stored meta-data regularly, just as you would refresh your local copy of the category meta-data regularly.

As most of the meta-data changes do not cause changes to the schema itself, it is often not possible for eBay to manage the changes through compatibility levels. For developers of third-party applications, this means it can be difficult to keep up with changes if you hard-code the meta-data in your application.

In addition, the library of possible attributes and values is quite large. This means it is not practical for most developers to try to look up all the attributes and values, all the validation rules, and all the dependencies between specific attributes and values in the documentation.

To help you keep Item Specifics and Pre-filled Item Information meta-data up to date, make the meta-data changes more transparent, and help you implement these features more quickly, the API includes a set of data-driven calls that let you import, update, and render the meta-data and product data dynamically. This approach lets you focus more of your development effort on handling the Item Specifics that the user selects and passing that data in the AddItemCall request.

In addition to attribute and product details, the meta-data includes features to help you validate the user's attribute selections and control how eBay handles listings that include invalid attribute data (see Validating Attribute Data Before Listing Items and Attribute Error Handling).

This chapter describes how to accomplish the following tasks:

Use the interfaces and sample classes (AttributeMaster and CategoryCSDownloader) provided in the Attributes Library to determine which categories support Item Specifics and which ones support Pre-filled Item Information. The category data that is returned defines mappings between attribute-enabled categories and the IDs of all the currently defined characteristic sets, plus other information. See Retrieving Category-to-Meta-Data Mappings for details on how to execute this call.
Use the interfaces and sample classes (AttributeMaster and AttributesXmlDownloader) provided in the Attributes Library to retrieve the attribute meta-data for one or more categories that support Item Specifics. See Retrieving Item Specifics Meta-Data for details on how to execute this call.
Use the interfaces and sample classes (AttributeMaster and AttributesXslDownloader) provided in the Attributes Library to retrieve the Item Specifics SYI XSL stylesheet that you can use to render Item Specifics and return policies in a user interface. You can use this stylesheet to render standard Item Specifics (if the seller is listing the standard way) and to render pre-filled Item Specifics (if the seller is listing with Pre-filled Item Information). See Retrieving the Item Specifics SYI XSL Stylesheet for details on how to execute this call.

See Summary of Listing the Standard Way with Item Specifics and Return Policies for information about why we strongly recommend that you use the XSL stylesheet.

For applications that support listing with Pre-filled Item Information, this chapter also describes ho to accomplish the following tasks:

Use GetProductSearchPageCall to retrieve product search page meta-data for one or more categories that support single-attribute product searches. See Retrieving Product Search Page Meta-Data for details on how to execute this call.
Use GetProductFinderCall to retrieve product finder meta-data for one or more categories that support product finder-style searches. See Retrieving Product Finder Meta-Data for details on how to execute this call.
Use GetProductFinderXSLCall to retrieve the Product Finder XSL stylesheet that you can use to render a Product Finder in a user interface. You can use this stylesheet to render the Product Finder XML returned from GetProductFinderCall. See Retrieving the Item Specifics SYI XSL Stylesheet for details on how to execute this call.

The Attributes Demo sample in the Samples\ASP.NET\AttributesDemo directory demonstrates a basic application that uses Item Specifics.

In general, your implementation of the meta-data calls should follow this usage pattern:

The first time you execute each call, retrieve all the available data.
Store all the returned data locally, along with the version of the data (each call returns the version value as a separate field).
Use the locally stored data to present Item Specifics or catalog product search criteria to a seller during the listing flow.
The next time you execute each call (usually no more often than once a day), use the stored version information as a filter to retrieve only the meta-data that has changed since the last time you executed the call.

Figure 19-1 illustrates this usage pattern in relation to maintaining Item Specifics meta-data. You could use a similar pattern to maintain catalog product meta-data. If you implement your own data-source providers, you should understand this usage pattern.

Figure 19-1 Retrieving and Maintaining Item Specifics Meta-Data

Later chapters in this documentation describe how to apply the XSL stylesheets to transform the XML into HTML, how to handle the user's selections, and how to list an item with the Item Specifics or Pre-filled Item Information the user selected.

This chapter covers the following topics:

Retrieving Category-to-Meta-Data Mappings

Retrieving Item Specifics Meta-Data

Retrieving the Item Specifics SYI XSL Stylesheet

Retrieving Product Search Page Meta-Data

Retrieving Product Finder Meta-Data

Retrieving the Product Finder XSL Stylesheet