## Appendix B. SUSE Manager API Access¶

In an effort to provide customers with added flexibility, SUSE Manager makes an application programming interface (API) available. This interface can be found by clicking Help at the top-right corner of the SUSE Manager website, then clicking API in the left navigation bar.

The SUSE Manager API is based upon XML-RPC, which allows distinct pieces of software on disparate systems to make remote procedure calls using XML over HTTP. For this reason, any calls you make are expected to meet the constraints of XML-RPC. You can find out more at http://www.xmlrpc.com/.

This section bypasses a list of available methods and classes in favor of tips for using the API efficiently. These include steps for determining required values and a sample script that makes some of the calls.

## B.1. Using the auth Class and Getting the Session¶

It is worth noting that you will almost invariably use the auth class first. This class offers a single method, login. Use this to establish an SUSE Manager session. It requires values for three parameters: username, password, and duration. The first two come directly from your SUSE Manager account, while the third is the length of time the session should last in seconds, typically 1200. It returns a session string than can be used in all other methods.

## B.2. Obtaining the system_id¶

Many of the methods require a value for the `system_id` parameter. This is the unique alphanumeric value assigned to each system when registered to SUSE Manager. It can be found within the `/etc/sysconfig/rhn/systemid` file on each machine. In addition, you may use the `download_system_id` method within the system class to obtain the value.

## B.3. Determining the sid¶

Several methods require a value for the `sid`, or server ID, parameter. Note that this is different from the `system_id`. You may determine the `sid` of a machine in two different ways. First, you can log into the SUSE Manager website, click the name of a system, and view the `sid` at the end of the URL in the location bar. It follows the `=` symbol and is part of a string that resembles the following: `index.pxt?sid=1003486534` . Second, you may use the `list_user_systems` method within the system class to obtain a list of systems available to the user that contains the associated `sid`s.

## B.4. Viewing the cid¶

Like servers, channels have their own IDs. This value, the `cid`, is a required parameter for some methods, including `set_base_channel` and `set_child_channels`. Also like the `sid`, the `cid` can be obtained through the SUSE Manager website. Just click on the name of a channel and view the end of the URL. It follows the `=` symbol, as part of a string that resembles the following: `details.pxt?cid=54` .

## B.5. Getting the sgid¶

System groups also have their own IDs. This value, the `sgid`, is a required parameter for the `set_group_membership` method, for instance. Like the `sid` and `cid`, the `sgid` can be obtained through the SUSE Manager website. Just click on the name of a system group and view the end of the URL. It follows the `=` symbol, as part of a string that resembles the following: `details.pxt?sgid=334958` . Note that the member parameter within the `set_group_membership` method requires only `yes` or `no` as input to make the association.

## B.6. Channel Labels¶

The architecture of a channel is not always clear from the channel label. Below is a list that shows the correspondence between channel labels and the official title of the architecture they serve.

Table B.1. Channel Labels

Channel Label | Platform
--- | ---
channel-i386-sun-solaris | i386 Solaris
channel-ia32 | IA-32
channel-ia64 | IA-64
channel-sparc | Sparc
channel-alpha | Alpha
channel-s390 | IBM S/390
channel-s390x | IBM System z
channel-iSeries | IBM eServer System i
channel-pSeries | IBM eServer System p
channel-x86_64 | AMD64 and Intel EM64T
channel-ppc | PPC
channel-sparc-sun-solaris | Sparc Solaris

This is particularly necessary to know for the channel.software.create method.

## B.7. Sample API Script¶

The following sample script depicts how to construct an SUSE Manager API client. Review the comments and links for a full discussion of the calls made.

    #!/usr/bin/perl -w

    use strict;
    use Frontier::Client;
    use Data::Dumper;

    ############################################################################
    # This is a sample script for use of the experimental Management APIs.     #
    # The API is currently available using XMLRPC only, which is described in  #
    # depth at:                                                                #
    #                                                                          #
    # http://www.xmlrpc.com/                                                   #
    #                                                                          #
    # We use the Frontier modules, available from:                             #
    #                                                                          #
    # http://theoryx5.uwinnipeg.ca/mod_perl/cpan-search?dist=Frontier-RPC      #
    #                                                                          #
    ############################################################################

    ############################################################################
    #   Defining an XMLRPC session.                                            #
    ############################################################################

    # Define the host first.  This will be the FQDN of your SUSE Manager system.
    my $HOST = '.yourdomain.com';

    # Now we create the client object that will be used throughout the session.

    my $client = new Frontier::Client(url => "http://$HOST/rpc/api");

    # Next, we execute a login call, which returns a session identifier that will
    # be passed in all subsequent calls.  The syntax of this call is described at:
    #
    #   http://$HOST/rpc/api/auth/login/

    my $session = $client->call('auth.login', 'username', 'password');

    ############################################################################
    #   System calls.                                                          #
    ############################################################################

    # This next call returns a list of systems available to the user.  The
    # syntax of this call is described at:
    #
    #   http://$HOST/rpc/api/system/list_user_systems/
    #
    # In the code snippet below, we dump data about our systems, and we
    # capture the ID of the first system we find for future operations.

    my $systems = $client->call('system.list_user_systems', $session);
    for my $system (@$systems) {
      print Dumper($system);
    }
    print "\n\nCapturing ID of system @$systems[0]->{name}\n\n";
    my $systemid = @$systems[0]->{id};

    # This next call returns a list of packages present on this system.  The
    # syntax of this call is described at:
    #
    #   http://$HOST/rpc/api/system/list_packages/
    #
    # This will probably be a pretty long list.

    my $packages = $client->call('system.list_packages', $session, $systemid);
    for my $package (@$packages) {
      print Dumper($package);
    }

    # Additional system calls are described at:
    #   http://$HOST/rpc/api/system/