AgileApps Support Wiki Pre Release

Difference between revisions of "REST API:package Resource"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
Line 126: Line 126:


;Request:
;Request:
:<syntaxhighlight lang="xml" enclose="div">
:The format of the request is the same as that returned by a package [[#Get a Package a Record|GET]].
<platform>
    <package>
        <id>{package_id}</id>
        ...
    </package>
</platform>
</syntaxhighlight>


;Response:
;Response:

Revision as of 21:59, 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

Lock-tiny.gif

Users that have the Manage Packages permission can use this resource. 
Method
GET
URI
https://{domain}/networking/rest/package
Response
<syntaxhighlight lang="xml" enclose="div">

<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>   
       <name>Our Application</name>
       <description>...</description>
       <managed>false</managed>
       <subscribed>true</subscribed>
       <version>2.0</version>
   </package>
    ...

   <message>
       0
       <description>Success</description>
   </message>
   <recordCount>N</recordCount>

</platform> </syntaxhighlight>

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.

Lock-tiny.gif

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
<syntaxhighlight lang="xml" enclose="div">

<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>  
       <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>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Add a Package

Template:Capability

Lock-tiny.gif

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
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
       <id>...</id>   
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Update a Package

Template:Capability

Lock-tiny.gif

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
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Delete a package Record

Template:Capability

Lock-tiny.gif

Users that have the Manage Packages permission can use this resource. 
Method
DELETE
URI
https://{domain}/networking/rest/package/{package_id}
Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Publish a Package

Template:Capability

Lock-tiny.gif

Users that have the Manage Packages permission can use this resource. 
Method
POST
URI
https://{domain}/networking/rest/package/operation/publish/{package_id}
Request
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <package>
       <field>data</field>
        ...
   </package>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
       <id>...</id>   
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Subscribe to a Package

Use this resource to install a Package.

Lock-tiny.gif

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
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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.

<syntaxhighlight lang="java" enclose="div" style="overflow: auto">

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();
       }
   }

} </syntaxhighlight>

Download a Package

Download a package as a zip file.

Lock-tiny.gif

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
<syntaxhighlight lang="xml" enclose="div">

103832778631715 

    content-type: application/xml

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

103832778631715

content-type: application/octet-stream

Encoded file part

103832778631715--

</syntaxhighlight>

  • On failure it will contain just a single part which looks something like this
<syntaxhighlight lang="xml" enclose="div">

103832778631715 

    content-type: application/xml

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

103832778631715--

</syntaxhighlight>

See also: REST API Error Codes

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.

<syntaxhighlight lang="java" enclose="div" style="overflow: auto">

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();
       }
   }

}

</syntaxhighlight>

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.

Lock-tiny.gif

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
<syntaxhighlight lang="xml" enclose="div">

<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> </syntaxhighlight>

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

<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
       <id>...</id>        
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Fields

package
Name Type Required on Add Description Additional Info
id String Checkmark.gif The package installation ID The value that appears as the id value in the Installation Link part of the Package page.
deployConfiguration
Name Type Required on Add Description Additional Info
tenantList List Checkmark.gif List of tenants to deploy the package to
notifyTenants Boolean Checkmark.gif If true, send a message to notify tenants about package deployment
deployTime Date Checkmark.gif Deployment date/time
0=Deploy immediately		 UTC Format
tenantList
Name Type Required on Add Description Additional Info
tenantId String Checkmark.gif Tenant ID
Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=REST_API:package_Resource&oldid=10851"