Difference between revisions of "REST API:package Resource"

Revision as of 22:44, 5 October 2011

This resource provides the ability to manage packages using the REST API.

Learn more: REST API Conventions and Considerations.

List All Packages

Users that have the Manage Packages permission can use this resource.

Method: GET

URI: https://{domain}/networking/rest/package

Response

<platform>
    <package>
        <date_created>2011-09-20T17:15:25.000Z</date_created>
        <date_modified>2011-09-20T17:15:25.000Z</date_modified>
        <created_id type="USER" ...>xyz123rty345</created_id>
        <modified_id type="USER"...>xyz123rty345</modified_id>
        <id>1555611998did1747697276</id>   <!-- Package ID -->
        <name>Our Application</name>
        <description>...</description>
        <managed>false</managed>
        <subscribed>true</subscribed>
        <version>2.0</version>
    </package>
     ...

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
    <recordCount>N</recordCount>   <!-- Number of package records returned -->
</platform>

See also: REST API:Error Codes

Get a Package Record

Retrieve package details, including a subscribe link and a list of the package elements it contains.

Users that have the Manage Packages permission can use this resource.

__TBD: Sufficient? Or is Publish Package tenant capability required?__

Method: GET

URI: https://{domain}/networking/rest/package/{package_id}

Response

<platform>
    <package>
        <date_created>2011-04-21T15:46:48.000Z</date_created>
        <date_modified>2011-04-21T15:46:48.000Z</date_modified>
        <created_id type="USER" ...>xyz123rty345</created_id>
        <modified_id type="USER" ...>xyz123rty345</modified_id>
        <subscribe_link 
            uri="https://{platform}/networking/Service?t=734&id=z69h84rd92"</subscribe_link>
        <id>28ad1a182c644235bfa6c278d66b182b</id>  <!-- Package ID -->
        <name>Order Processing</name>
        <description/>
        <managed>false</managed>
        <subscribed>false</subscribed>
        <version>1.1</version>
        <packageItems>
            <packageItem>
                <id>094d26aec226dbc33b9dcc</id>
                <type>1</type>
                <dependent>false</dependent>
            </packageItem>
            ...
        </packageItems>

        <revisions>
            <revision>
                <version>1.1</version>
                <versionNotes>Trial Version</versionnotes>
            </revision>
            ...
        </revisions>
    </package>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Add a Package

Template:Capability

Users that have the Manage Packages permission can use this resource.

Method: POST

URI: https://{domain}/networking/rest/package

Request: The format of the request is the same as that returned by a package GET.

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>   <!-- ID of the newly created package -->
    </message>
</platform>

See also: REST API:Error Codes

Update a Package

Template:Capability

Users that have the Manage Packages permission can use this resource.

Method: PUT

URI: https://{domain}/networking/rest/package/{package_id}

Request: The format of the request is the same as that returned by a package GET.

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Delete a package Record

Template:Capability

Users that have the Manage Packages permission can use this resource.

Method: DELETE

URI: https://{domain}/networking/rest/package/{package_id}

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Publish a Package

Template:Capability

Users that have the Manage Packages permission can use this resource.

Method: POST

URI: https://{domain}/networking/rest/package/operation/publish/{package_id}

Request: none

Response

<platform>
    <package>                               
        <revisions>
            <revision>
                <version>1.2</version>
                <versionNotes>new object added</versionNotes>
                <override>true</override>
            </revision>
            ...
    </revisions>
    </package>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Subscribe to a Package

Use this resource to install a Package.

Users that have the Manage Packages permission can use this resource.

Template:Capability

Method: POST

URI: https://{domain}/networking/rest/package/operation/subscribe?{query_parameters}

Query Parameters

packageId - This is the package installation ID -- the value that appears as the id value in the Installation Link part of the Package page.
fileName - The path to the package file, when subscribing to a downloaded copy of the package. (Install from File tenant capability must be enabled to use this option.)

For more information, see: Specifying Query Parameters in REST APIs

Examples

Subscribe from repository:

https://{domain}/networking/rest/package/operation/subscribe?packageId=123123123

Subscribe from repository, specifying a version number:

https://{domain}/networking/rest/package/operation/subscribe?packageId=123123123&version=1.2

Subscribe from a file:

https://{domain}/networking/rest/package/operation/subscribe?fileName=C:\package.zip

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Sample Package Subscribe Client

The PackageSubscribeClient demo program extends the REST API:BaseClient class to subscribe to a package file (a zip file downloaded from the platform). With minor modifications, it can be used to subscribe to a package hosted on the platform.

package demo.rest;

import java.io.File;

import javax.ws.rs.core.MediaType;

import org.apache.wink.client.ClientResponse;
import org.apache.wink.client.ClientWebException;
import org.apache.wink.client.Resource;
import org.apache.wink.common.internal.utils.MediaTypeUtils;

/**
 * "Subscribe" to (install or update) a package contained in a zip file. 
 * This program extends demo.rest.BaseClient.java 
 * which in turn makes use of demo.rest.BaseUtil.java to handle
 * logging in, logging out, and message formatting.
 */
public class PackageSubscribeClient extends BaseClient
{
   
    public static void main(String[] args)
    {
        String packageUrl = baseUrl + "/package/operation/subscribe"
               + "?fileName=orders.zip";         // Subscribe from a file
        File f = new File("c:\\orders.zip");

        //Other options:
        //     + "?packageId=123123123";       // Subscribe from platform
        //     + "?packageId=123123123&version=1.2";  //  Specify version

        // Instantiate BaseClient.client and get sessionId
        PackageSubscribeClient subscribeClient = new PackageSubscribeClient();
        cookieString = subscribeClient.login(); 
        try
        {
           Resource resource = getResource(packageUrl);
           resource.header("Cookie", cookieString);

           ClientResponse response =
                resource.contentType(MediaTypeUtils.ZIP).accept(
                    MediaType.APPLICATION_XML).post(ClientResponse.class, f);
            String responseXml = response.getEntity(String.class);
            echoResponse(responseXml);
        }
        catch (ClientWebException webException)
        {
            echoResponse(webException);
        }
        catch (Exception e)
        {
           System.out.println(e.getMessage());
           e.printStackTrace();
        }
        finally
        {
            client.logout();
        }
    }
}

Download a Package

Download a package as a zip file.

Users that have the Manage Packages permission can use this resource.

Method

POST

URI

https://{domain}/networking/rest/package/operation/download/{package_id}?{query_parameters}

where:

package_id - Is the package record ID - the value at the top of the Package page.

Query Parameters

lastPublishedVersion

If TRUE, the package downloaded will be the last published version. (Default) If the package has never been published, it will be published first, so that it can be downloaded.
If FALSE, the package will be re-assembled/re-created, and this version will include all changes made to the components, from the last package publish date. (If any components of the package have been checked out, the request returns an Error.)

For more information, see: Specifying Query Parameters in REST APIs

Response

The response is of type multipart/mixed.

On success it will contain two parts which look something like this

-----------------------------103832778631715
     content-type: application/xml
 
     <platform>
        <message>
            <code>0</code>
            <description>Success</description>
        </message>
    </platform>
 
-----------------------------103832778631715
content-type: application/octet-stream
 
Encoded file part
-----------------------------103832778631715--

On failure it will contain just a single part which looks something like this

-----------------------------103832778631715
     content-type: application/xml
 
     <platform>
        <message>
            <code>0</code>
            <description>Success</description>
        </message>
    </platform>
-----------------------------103832778631715--

Sample Package Download Client Program

The PackageDownloadClient demo program extends the REST API:BaseClient class to download a package from the platform to your local system.

package demo.rest;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;

import org.apache.wink.client.ClientResponse;
import org.apache.wink.client.ClientWebException;
import org.apache.wink.client.Resource;
import org.apache.wink.common.internal.utils.MediaTypeUtils;
import org.apache.wink.common.model.multipart.InMultiPart;
import org.apache.wink.common.model.multipart.InPart;

/**
 * Download a package from the platform to the local system.
 * This program extends demo.rest.BaseClient.java 
 * which in turn makes use of demo.rest.BaseUtil.java to handle
 * logging in, logging out, and message formatting.
 */
public class PackageDownloadClient extends BaseClient
{

    public static void main(String[] args)
    {
        // packageId is the unique id associated with the package.
        // Get it from the platform UI while viewing a package.
        String packageId = "761fb822e95d48c498d4c4f97dd1470b";
        String lastPublishedVersion="true";
        String downloadPackageUrl = baseUrl + "/package/operation/download/"
                  + packageId+"?lastPublishedVersion="+lastPublishedVersion;

        // Instantiate BaseClient.client and get sessionId
        PackageDownloadClient client = new PackageDownloadClient();
        cookieString = client.login(); 
       try
        {
            Resource resource = getResource(downloadPackageUrl);
            resource.header("Cookie", cookieString);

            ClientResponse response =
                resource.accept(MediaTypeUtils.MULTIPART_MIXED).post(
                    ClientResponse.class, "");

            InMultiPart iMultiPart = 
                response.getEntity(InMultiPart.class);

            while (iMultiPart.hasNext())
            {
                InPart iPart = iMultiPart.next();
                String contentType = iPart.getContentType();
                if (contentType.contains(MediaType.APPLICATION_XML))
                {
                    InputStream ips = iPart.getInputStream();
                    echoResponse(ips);
                }
                else if (contentType.contains(MediaType.APPLICATION_OCTET_STREAM))
                {
                    MultivaluedMap<String, String> headers = iPart.getHeaders();
                    String cDHeader = headers.getFirst("Content-Disposition");

                    String fileName = "";
                    Pattern p = Pattern.compile("filename=.*");
                    Matcher m = p.matcher(cDHeader);
                    if (m.find())
                    {
                        fileName = m.group();
                    }

                    fileName = fileName.replace("filename=", "");
                    File packageZipFile = new File("c:\\" + fileName);
                    FileOutputStream fos = null;
                    fos = new FileOutputStream(packageZipFile);

                    InputStream is = iPart.getInputStream();
                    int size = 0;
                    int i = 0;
                    byte[] ba = new byte[8196];
                    while ((i = is.read(ba)) != -1)
                    {
                        fos.write(ba, 0, i);
                        size += i;
                    }
                    fos.close();
                    System.out.println("Package downloaded to " 
                        + packageZipFile.getAbsolutePath());
                }
                else 
                {
                    System.out.println("Unrecognized media type: " + contentType);
                }
            }
        }
        catch (ClientWebException webException)
        {
            echoResponse(webException);
        }
        catch (IOException io)
        {
            io.printStackTrace();
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
        finally
        {
            client.logout();
        }
    }
}

Deploy a Package

Deploy a package to a list of tenants, where both the package to deploy and the tenant list are specified in the request.

Users that have the Manage Packages permission can use this resource, and Mass Deployment of Packages to Tenants must be enabled for the publishing tenant.

Method: POST

URI: https://{domain}/networking/rest/package/operation/deploy

Request

<platform>
    <package>
        <id>123123123</id>              --package installation ID
        <deployConfiguration>
            <tenantList>
                <tenantId>1214573329</tenantId>
                <tenantId>1224242818</tenantId>
                  ...
            </tenantList>
            <notifyTenants>false</notifyTenants>
            <deployTime>0</deployTime>  
        </deployConfiguration>
    </package>
</platform>

Response

Returns the id of the submitted import job, along with a message telling whether or not the job was accepted for processing. (Use the REST packageDeploy Status resource to follow the progress of the job.)

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>      <!-- job ID for the deployment process -->  
    </message>
</platform>

See also: REST API:Error Codes

Fields

Note: Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".

Name	Type	Attribute	Required on Add	Description	Additional Information
xyz	String	Read Only		Descr	AddlInfo
xyz	String	Writable on Add only	Req'd	Descr	AddlInfo

package

Name	Type	Attribute	Description	Additional Information
`id`	String	Read Only	The package installation ID	The value that appears as the id value in the Installation Link part of the Package page.
objectId	String	Read Only	PACKAGE
date_modified	Date	Read Only		UTC Format
date_created	Date	Read Only		UTC Format
created_id	Lookup	Read Only		User ID
modified_id	Lookup	Read Only		User ID
subscribe_link	String	Read Only	Link to use to subscribe to (install) the package.	Available only to the package publisher
subscribed	Boolean	Read Only	The package has been installed.
version	String	Read Only	Latest published version
revisions	List	Read Only	List of package versions	Revision number is automatically incremented when a package is published.
name	String		Package Name
description	String		Package description
managed	Boolean	Can change to true	True if the package is locked.	Once locked, this value cannot be changed back to false.
packageItems	List		Package items	(See table that follows.)

packageItem

Name	Type	Attribute	Required on Add	Description	Additional Information

packageItem types

Value	Type

publish package

Name	Type	Attribute	Required on Add	Description	Additional Information

deployConfiguration

Name	Type	Description	Additional Information
`tenantList`	List	List of tenants to deploy the package to
`notifyTenants`	Boolean	If true, send a message to notify tenants about package deployment
`deployTime`	Date	Deployment date/time 0=Deploy immediately	UTC Format

tenantList

Name	Type	Attribute	Required on Add	Description	Additional Information
`tenantId`	String			Tenant ID

@@ Line 383: / Line 383: @@
 |}
-:;packageItem types:
+::;packageItem types:
 ::{| border="1" cellpadding="5" cellspacing="1"
 ! Value!!Type

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

Difference between revisions of "REST API:package Resource"

Revision as of 22:44, 5 October 2011

Contents

List All Packages

Get a Package Record

Add a Package

Update a Package

Delete a package Record

Publish a Package

Subscribe to a Package

Sample Package Subscribe Client

Download a Package

Sample Package Download Client Program

Deploy a Package

Fields

package

packageItem

publish package

deployConfiguration

tenantList