Application Packaging Standard

Last updated 14-Nov-2018

Browsing APS Catalog

The simplest way to browse APS Catalog is to display all its contents. To perform this, a client must do the following:

  1. Retrieve a Repository index.
  2. Discover the Repository feed.
  3. Retrieve the feed and display its content to end users.

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.

Retrieving Repository Index

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:

  1. Request the System index by issuing the HTTP GET request to http://www.example.com/aps/.
  2. Parse the index for the following expression: /a[@class='repository']. The href attribute of each such element contains a URL of a Repository index. The element content contains the repository name.
  3. Request the required Repository index by issuing the HTTP GET request to a corresponding URL.

Discovering Repository Feed

To retrieve a Repository feed URL, a client must parse the Repository index for the following expression: /a[@id='feedLink']/@href/text().

Retrieving Repository Feed and Displaying Its Content

To display feed content to end users, a client must perform the following steps:

  1. Retrieve the feed by issuing an HTTP GET request to the feed URL.

    1. If APS Catalog returns the status code 304, fetch the feed from cache.
    2. If APS Catalog returns a feed, save the feed to cache.
  2. Parse the requested feed page for navigation bar links:
    • First feed page link: /link[@rel='first']/@href/text()
    • Previous feed page: /link[@rel='prev']/@href/text()
    • Next feed page link: /link[@rel='next']/@href/text()
    • Last feed page link: /link[@rel='last']/@href/text()
  3. 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.

  1. Render a web page with the navigation bar and transformation results and display the page to end users.

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.

Advanced Browsing

To provide end users with advanced browsing capabilities, a client can use one of the following APS Catalog features (or their combination):

  • Filters
  • Search descriptions

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.

Filters

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:

  1. Retrieve vendor names and links to Vendor indexes from a Repository index.
  2. Display vendors list to a user.
  3. Retrieve an index corresponding to the vendor (after the user chooses one of the vendors).
  4. Fetch a feed link from the index.
  5. Display the feed content to the user.

This example outlines the routine of using such filters. It is as follows:

  1. A client retrieves descriptions of lower-level indexes and links to these indexes from a current index. For instructions on how to do it, see Retrieving Information from Indexes.
  2. The client displays these descriptions as filter names to a user.
  3. The user chooses one of the filter names.
  4. The client extracts a feed link from an index corresponding to the filter name. For instructions on how to do it, see Discovering Feeds.
  5. The client displays feed content to the user. As all feeds have the same syntax, this step is performed using the same instructions as described in Retrieving Repository Feed and Displaying Its Content.

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:

  1. Retrieve a Repository index.

  2. Extract a list of packagers by parsing the index for the //select[@id='packager'].

  3. 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.

  1. Display the feed content on a user’s request.

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

<categories>

<category id="Back office" package_count="9" name="Back office">

<category id="Back office/Manufacturing Solutions" package_count="2"

name="Manufacturing Solutiocount="1" name="Accounting & Financial" />

...

</categories>

/vendors Returns a list of all vendors. Each vendor provides at least one accessible package

<vendors>

<vendor id="aerialchat.sourceforge.net" />

<vendor id="anyinventory.sourceforge.net" />

...

</vendors>

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.

Service Operations

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.

Discovering Feeds

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.

Retrieving Information from Indexes

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 Descriptions

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:

  1. Define the number of entries to be displayed per feed page. Let X denotes this number.
  2. Retrieve the first feed page by issuing an HTTP GET request <feed_URL>?pageSize=X.
  3. Retrieve the total number of entries in the feed by parsing the first feed page for //feed/opensearch:totalResults/text(). Let Y denote this number.
  4. Calculate the number of feed pages by rounding Y / X.
  5. Create links to each feed page. Each link will look like this: <feed_URL>?pageSize=X&page=N. Here N stands for a feed page 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.