APS Catalog API Overview

This chapter provides description APS Catalog API features. It is divided into the following sections:

• Technical Details Contains information on protocols and formats supported by APS Catalog API.
• APS Catalog Resources Describes resources provided by APS Catalog through API.
• APS Catalog API Operations Lists operations on the APS Catalog resources.

Technical Details

A client interacts with APS Catalog by issuing HTTP GET/POST requests, and retrieving HTTP packets with status codes and APS Catalog resources. A resource can be a binary file (for example, a package) or an XML-based message. Each XML message conforms to one of the following formats:

1. Atom feed [RFC 4287] with the following extensions:

   • OpenSearch 1.1
   • Feed paging [RFC 5005]
   • Native APS Catalog extensions describing APS package metadata

2. XHTML format that describes APS catalog structure.

3. Native XML-based format that describes APS catalog structure. For details, refer to APS Catalog Resources.

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 the 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 Version 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 Indexes 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 section 14.25 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 Feeds of the API Reference.

A client can limit the number of entries in a requested feed by adding specific arguments to the feed request. 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 can be 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 Search Descriptions of the API Reference.

APS Catalog API Operations

To use the API, a client sends HTTP requests to APS Catalog that instructs it to perform a RETRIEVE or ADD operation over a resource.

• A client performs RETRIEVE operations to obtain a specific index, feed, package source, package metadata, package certificate, or search description. To retrieve a resource, a client issues an HTTP GET request to the resource URL.

Important

APS Catalog processes feed requests differently from other requests. For details, refer to APS Catalog Resources

• A client performs an ADD operation to add a package to APS Catalog. Available methods are:

  • A client submits the packageSubmitForm form to APS Catalog.
  • A client submits an HTTP POST request to /packager/upload/ URL.

For details on the Add operations, refer to Managing APS Catalog Contents.

← Introduction

Browsing APS Catalog →