APS Catalog Resources

This section describes resources that a client accesses through APS Catalog API. The resources are divided into the following types:

Index. Contains information about APS Catalog hierarchy structure.
Feed. Contains information about the APS Catalog content.
Search description. Contains instructions on how to filter the APS Catalog content.
Package bits. Represent a package file.
Package metadata. Hold package metadata.
Package resources. Comprise additional files included into a package.
Package certificate. Holds a package certificate.

Note: APS Catalog represents each package as three resources: package bits, package metadata, and package resources.

The following diagram depicts the organization of APS Catalog resources:

The diagram shows that all resources are directly or indirectly linked with indexes - read-only XHTML data that hold information about APS Catalog hierarchy structure.

The following table shows references that are provided by a specific index.

Index Name	Link to Parent index	Link to Child indexes	Feed link	Link to package bits	Link to Package metadata	Link to package certificate	Link to package resources
Service index		+	+
Repository index	+	+	+
Vendor index	+	+	+
Application index	+	+	+
Application Version index	+	+	+
Package index	+	+	+	+	+	+
Package Resources index	+						+

In terms of file systems, indexes describe APS Catalog directories, each containing links to its content, parent directory, and subdirectories. A client can request an index at a specific URL. For details on index URLs and elements included in indexes, refer to the Indexes section of the API Reference.

As noted, almost every index has a feed link. If indexes represent the structure of APS Catalog, feeds represent its content. More precisely, a feed is composed of entries, each providing details on a single package. The details include a package name, vendor, version, etc.

APS Catalog provides five read-only Atom feeds:

Repository feed. Contains details on each package within a repository.
Vendor feed. Contains details on each package produced by a specific vendor.
Application feed. Contains details on each package of a specific application. More precisely, each entry in this feed represents a package that differs from other packages by a packager, application version, or both.
Application Version feed. Contains details on each package of the same application version issued by different packagers.
Package Updates feed. Contains details on each package that updates a specific application. If a package does not have any updates, the Package Updates feed is empty.

A client can request a feed at the URL retrieved from a corresponding index. There are two features of how APS Catalog operates with feed requests.

APS Catalog returns paged feeds. This means that APS Catalog divides a feed into parts before sending it to a client. This enables such client to request only a part of data, display it, and request the next part only if a user requests it. More precisely, a paged feed is a set of linked feeds that together contain all entries requested by a client. We will refer to each such paged feed part as to a feed page. Each feed page has links to the first feed page and the last feed page. Additionally, each feed page contains a link to the previous feed page and the next feed page (if these pages exist). Hereafter in this guide, terms "paged feed" and "feed" have the same meaning.

For details on paged feeds, refer to [RFC 5005].
APS Catalog returns only modified feeds. This means that APS Catalog can return only feed entries that were modified since the last client's request. To fetch only these entries, a client must specify the last time of feed request in the If-Modified-Since parameter nested in the request header. If a client does not provide this information, APS Catalog returns all feed entries. For details on the If-Modified-Since parameter, refer to the 14.25 section of [RFC 2616]. Note, that to display all feed entries instead of only updated ones, a client must somehow cache all retrieved entries.
For details on feed URLs and XML structure, refer to the Feeds section of the API Reference.

A client can limit the number of entries in a requested feed by adding specific arguments to the feed request. For instance, a client can request a Repository feed restricted to entries which describe only Gold certified packages (for details on certification levels, refer to the Site Application Certification Criteria document). These arguments are feed specific. APS Catalog stores the request arguments in resources called search description documents. Hereafter in this guide, we will refer to these resources as to search descriptions. One search description corresponds to a single feed. Search descriptions conform to the search description format. For details on search descriptions format, see OpenSearch specification .

APS Catalog provides the following search descriptions:

Repository search description
Vendor search description
Application search description
Application Version search description

As it is seen from the list, only four feeds have search descriptions, namely: Repository, Vendor, Application and Application Version.

A client can request a search description at a specific URL. For details on search description URLs and XML structure, refer to the Search Descriptions section of the API Reference.