The download-package operation is used to download an application package from an APS Catalog.

If the operation succeeds, a download task is created.

Request Packet Structure

A request XML packet that downloads an application package from an APS Catalog includes the download-package operation node:

<packet>
    <aps>
        <download-package>
            ...
        </download-package>
    </aps>
</packet>

The download-package node is structured as follows:

• package, required

  Holds a collection of data describing target package. Data type: APSIdentifierType (aps.xsd).

  Values of the child nodes should be taken from the corresponding elements of an APS catalog feed entry that describes a package to be downloaded. For the detailed information, refer to the Feeds: Elements Reference section of the APS Catalog API Reference.

• name, required

  Specifies the application package name. Data type: string.

• version, optional

  Specifies the application version. Data type: string.

  If not defined, and there are several versions of the application in APS catalog, package of the highest version will be downloaded.

• release, optional

  Specifies the package release. Data type: string.

  If not defined, and there are several releases of the package in APS catalog, package of the highest release will be downloaded.

• vendor, optional

  Specifies the application vendor. Data type: string.

• packager, optional

  Specifies the application packager. Data type: string.

• is_uploaded, optional

  This option is not used with this operation.

• is_visible, optional

  This option is not used with this operation.

  aps-catalog-url, optional

  Specifies the URL of APS Catalog from which the package should be downloaded. Data type: string

  If the node is present, the URL in its value should be exactly the same as it is defined in the APS Catalogs configuration file, otherwise the error with code 1013 is received.

  If not included in a packet, the package is downloaded from the APS Catalog which is defined first in the APS Catalogs configuration file.

Response Packet Structure

The download-package node of the output XML packet is structured as follows:

• result, required

  Wraps the response retrieved from the server. Data type: resultType (common.xsd).

• status, required

  Specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

• errcode, required if the operation fails

  Returns the error code. Data type: integer.

• errtext, required if the operation fails

  Returns the error message. Data type: string.

• task-id, required if the operation succeeds

  Returns the ID of download task, which can be later used for retrieving the download status. Data type: string.

Samples

Installing an application package from a particular APS catalog

This packet installs an application package of particular version, release, vendor and publisher, and from a particular APS catalog (most probably, different from the default one).

<packet>
    <aps>
        <download-package>
            <package>
                <name>BlogEngine.NET</name>
                <version>1.4.5</version>
                <release>2</release>
                <vendor>www.dotnetblogengine.net</vendor>
                <packager>www.glowtouch.com</packager>
            </package>
            <aps-catalog-url>http://apscatalog.com/</aps-catalog-url>
        </download-package>
    </aps>
</packet>

Response:

<packet>
    <aps>
        <download-package>
            <result>
                <status>ok</status>
                <task-id>4</task-id>
            </result>
        </download-package>
    </aps>
</packet>

Downloading several packages with blog applications from the default APS Catalog

This package downloads several packages with blog applications from the default APS Catalog. It is supposed that the freshest in the Catalog packages of each application will be downloaded.

<packet>
    <aps>
        <download-package>
            <package>
                <name>BlogEngine.NET</name>
            </package>
        </download-package>
        <download-package>
            <package>
                <name>WordPress</name>
            </package>
        </download-package>
        <download-package>
            <package>
                <name>geeklog</name>
            </package>
        </download-package>
    </aps>
</packet>

Response:

<packet>
    <aps>
        <download-package>
            <result>
                <status>ok</status>
                <task-id>4</task-id>
            </result>
        </download-package>
    </aps>
</packet>

Such response is received in case the APS Catalog URL defined by the request is not listed in the APS Catalogs configuration file. It also covers the cases when the URL in request differs from the URL in the configuration file in the smallest details. For example, request misses the URL trailing slash while it is defined in the APS Catalogs configuration.

<packet>
    <aps>
        <download-package>
            <result>
                <status>error</status>
                <errcode>1013</errcode>
                <errtext>Catalog with URL "http://apscatalog.com" does not exist</errtext>
            </result>
        </download-package>
    </aps>
</packet>

Such negative response is received if the requested APS Catalog URL cannot be resolved:

<packet>
    <aps>
        <download-package>
            <result>
                <status>error</status>
                <errcode>1023</errcode>
                <errtext>Could not resolve host: apscatalog.co; No data record of requested type</errtext>
            </result>
        </download-package>
    </aps>
</packet>

Such negative response is received when an APS Catalogs configuration file has improper format:

<packet>
    <aps>
        <download-package>
            <result>
                <status>error</status>
                <errcode>1023</errcode>
                <errtext>APS Catalog configuration file is broken</errtext>
            </result>
        </download-package>
    </aps>
</packet>