The simplest way to browse APS Catalog is to display all its contents. To perform this, a client must do the following:
This chapter provides in-depth instructions on how to perform each of these steps. You can improve client flexibility in representation of APS Catalog resources making it filter the APS Catalog content. Such filtering enables end users to search for something particular in APS Catalog like “applications of a specific vendor”. A client can narrow search results by providing additional search parameters. These parameters make user requests more precise, and reduce the traffic between the client and APS Catalog. The guidelines on how to implement these extensions are also provided in this chapter. For details, see Advanced Browsing.
Some operations described in this chapter ivolve parsing XML data for specific elements. To identify such elements, we will use XPATH expressions.
In this document:
It is supposed that a client knows the Service index URL. For instance, this URL is http://www.example.com/aps/.
To retrieve a Repository index, the client must perform the following steps:
/a[@class='repository']. The href attribute of each such
element contains a URL of a Repository index. The element content contains the repository name.To retrieve a Repository feed URL, a client must parse the Repository index for the following
expression: /a[@id='feedLink']/@href/text().
To display feed content to end users, a client must perform the following steps:
Retrieve the feed by issuing an HTTP GET request to the feed URL.
- If APS Catalog returns the status code 304, fetch the feed from cache.
- If APS Catalog returns a feed, save the feed to cache.
/link[@rel='first']/@href/text()/link[@rel='prev']/@href/text()/link[@rel='next']/@href/text()/link[@rel='last']/@href/text()Extract the entry elements from the feed and transform them to the required format.
For details of the entry element, refer to Elements Reference in API Reference.
Note
Steps 2 and 3 are repeated on each feed page request. Step 3 can be easily performed by using XSL transformations.
A client can create a navigation bar that includes links to all feed pages. This requires utilizing search descriptions. For details on how to add the navigation bar, refer to Search Descriptions.
To provide end users with advanced browsing capabilities, a client can use one of the following APS Catalog features (or their combination):
Both filters and search descriptions affect the information on APS Catalog resources which is displayed to end users. By using filters/search descriptions, a client can reduce the incoming traffic value, and users can obtain more precise data. The difference between filters and search descriptions is that filters fetch particular feeds from APS Catalog indexes when forming a results set, while search descriptions contain rules that are applied to a certain feed (as request arguments) and affect the content of this feed.
The Filters and Search descriptions sections contain step-by-step instructions on how to filter the APS Catalog content. Some of these steps require additional explanations which are provided in a separate section named Service Operations.
A filter is a named rule which uses indexes to return only packages that meet a specific filtering criterion. For example, to filter packages by vendors, a client must perform the following steps:
This example outlines the routine of using such filters. It is as follows:
According to the APS, each package pertains to one or more packagers. A client can filter packages by their packagers. To do it, a client must perform the following steps:
Retrieve a Repository index.
Extract a list of packagers by parsing the index for the //select[@id='packager'].
Generate a feed link to each packager. Each such link looks as follows: <formAction>?<selectName>=<optValue>
Here
<formAction> stands for //form/@action/text()
<selectName> stands for //select/@name/text()
<optValue> stands for //select[@id='packager']/optgroup/option/@value/text().
For example, we have the following part of a Repository index:
<label for="packager">Packager</label>
<select id="packager" name="packager">
<option>www.parallels.com</option>
</select>
After parsing this part, a client must get a www.parallels.com packager with a feed link ../1.atom?packager=www.parallels.com.
Note
Feed content can be displayed with a browser. In this case, keep in mind that different browsers may handle feeds differently.
Remarks
You can use the same mechanism to filter the APS Catalog content by other parameters like target architectures, target platforms, etc.
APS Catalog offers two additional URIs to get lists of vendors and categories in XML formats. You can use these lists to form feed links that filter the APS Catalog content by vendor or category.
| URI | Description | Result example |
|---|---|---|
/categories |
Returns a list of all categories. There is at least one accessible package in each category |
|
/vendors |
Returns a list of all vendors. Each vendor provides at least one accessible package |
|
A client can perform even more complex filtering. To build this functionality into a client, you can use filters together with search descriptions, or request index resources with additional arguments. For details on search descriptions, refer to the next section. For details on what arguments can be added to index resource URL, refer to Indexes.
This section describes how to perform operations related to filtering of APS Catalog content. These operations include discovering a specific feed and extracting specific data from indexes.
Each APS Catalog index (except for Package Resources) has a feed link. To extract the feed link from an index, parse
such index for //a[@id='feedLink'].
Package Updates feed differs from other feeds by its semantics. This feed contains a list of packages that update
an application, rather than a list of application packages. To indicate this fact, a client must use //a[@id='updates']
to retrieve the Package Updates feed link from a Package index.
To create a filter, a client must fetch specific data from indexes (filter names, links to sub-indexes, etc). The data is nested in specific <A> tags. Each such tag provides information on an APS Catalog resource. The tag content is the human-readable resource name, the href attribute stores a link to the resource, and the ID/class attributes identify the tag. In most cases, the resource is a sub-index, and its name is used as the name of a filter, or the name of an APS Catalog hierarchy level. However, some indexes provide links to other resources like packages, package certificates, etc.
This section explains what expressions can be used to fetch these <A> tags from indexes. The section starts with parsing the System index to show that all APS Catalog resources can be recursively derived from this index.
Getting Data from the Service Index
Information on Repository indexes can be extracted from the Service index.
Expression: //a[@class='repository']
For details on the Service index XML structure, refer to Service Index in the API Reference.
Getting Data from a Repository Index
From a Repository index, a client can extract the following information:
Info on a Vendor index
Expression: //a[@class='vendor']
Info on categories
Expression: //select[@id='category']/optgroup
Info on packagers
Expression: //select[@id='packager']//option
List of available target architectures
Expression: //select[@id='arch']//option
List of available target platforms
Expression: //select[@id='platform']//option
List of available target OS
Expression: //select[@id='os']//option
List of available package types
Expression: //select[@id='type']//option
Info on package bits
Expression: //a[@id='aps']
Info on Application tags
Expression: //select[@id='tag']//option
Search description is an XML resource linked with a feed. This resource contains templates of feed requests that cause APS Catalog to tweak the content of a feed before returning it to a client. Each such template differs by arguments added to a feed URL. For instance, to get a feed page with 20 entries, a client must issue the following HTTP GET request: <feed_URL>?pageSize=20. To get the second feed page with 20 entries per page, a client must issue the following request: <feed_URL>?pageSize=20&page=2. These two arguments are common for each feed linked with a search description. For description of feed request arguments, refer to Search Descriptions. A typical usage of arguments nested in search descriptions is illustrated in the next paragraph.
How to create an extended navigation bar
A client can use the page and pageSize arguments to create a navigation bar that comprises links to all feed pages. It is supposed that such client has already discovered a feed. To generate the bar, the client must do the following:
//feed/opensearch:totalResults/text(). Let Y denote this number.Remarks
A client can check if search description arguments are updated by parsing the corresponding search description.
Feed request arguments can be used in combination with filters to create custom filtering criteria. For example, a client can display Gold certified packages pertaining to a specific APS category. We recommend you to examine the XML structure of each search description to make use of the full range of functionality provided by them. For details on search descriptions XML structure, see the API Reference, section Search Descriptions.