In my previous blog post, I covered how to navigate the SoftLayer Services website, and how to query the SoftLayer API efficiently. In this post, I'll cover additional aspects of using the SoftLayer API with the python client.

List of Services to Start Navigating From

If you read part 1 of the series, you have a lot of good techniques for querying the data of resources in SoftLayer such that from any service you can efficiently follow the data trail to other services to get to all of the information you want. The last big thing you need to know about querying the SoftLayer API is: Where are the best places in the enormous SoftLayer Services website to begin these trails? The Account service is a good place to start for many data types, but always starting there will not get you to everything. Even if you can eventually get to the data you want by starting with the Account service, there are often shortcuts to be found by starting somewhere else. I've put together a list of useful trail heads and what data types can be found down each trail. This is by no means an exhaustive list, but will hopefully get you started.

• Account
  • getNetworkVlans(): returns the network VLANs in the account, which can also get you to the subnets and primaryRouters
  • getHardware(): returns hardware, which gets you to datacenter, hardDrives, processors, memory, networkCards, operatingSystem which gets you to passwords
  • getVirtualGuests(): returns Virtual_Guest, which gets you to maxCpu, maxMemory, datacenter, operatingSystem
  • getCurrentUser(): returns User_Customer, which gets you to childUsers and permissions
  • getUsers(): returns all of the users in this account
  • getNetworkGateways(): returns the gateways (Vyattas), which gets you to the networkVlans associated to (routed by) the gateway, and then the subnets and primaryRouters
  • getTickets(): returns the tickets associated with an account
  • getOrders(): returns the orders for this account
• Location
  • getDatacenters(): returns datacenters, which can get you to routers, etc.
• Product_Package
  • getAllObjects(): returns the products that can be ordered
  • getConfiguration(): returns the categories of items (parts) of a product that can be specified when ordering it
  • getItemPrices(): returns the various parts of a product that can be specified when ordering it
• Billing_Order
  • getOrderStatuses(): returns the status for all orders of this account
• User_Customer
  • getChildUsers(): returns the users that are children of (i.e., created by) the current user

Services That Modify SoftLayer Resources

Now that you are an expert at querying the SoftLayer API, let's move on to SoftLayer API calls that modify SoftLayer resources. The basics are similar: Find the right service and method within that service, fill out a data structure similar to what it would be like if you queried it, and if this is an existing resource, use the id to identify it. There are many SoftLayer API methods that modify resources, but to give you a feel for what they are like, I'll list a few and then give you a detailed example of one.

• Hardware
  • editSoftwareComponentPasswords(): notifies SoftLayer that you changed the password of a CCI or bare metal server so it will display correctly in the SoftLayer portal and so SoftLayer support can access the CCI when you have a problem
• Network_Gateway
  • bypassVlans(): change a VLAN that is associated to a gateway from routed state to bypassed state
  • unbypassVlans(): change a VLAN that is associated to a gateway from bypassed state to routed state
• Network_Gateway_Vlan
  • createObjects(): associate VLANs to this gateway (i.e., have the gateway be the router for them)
  • deleteObjects(): disassociate VLANs from this gateway
• Product_Order
  • placeOrder(): order a resource from SoftLayer
  • verifyOrder(): verify that your order data structure is valid, but don't actually order the resource
• Billing_Item
  • cancelItem(): give a resource back to SoftLayer (for monthly items, they are still usable until the end of the month)

For our detailed example, we will associate VLANs to a network gateway. On the SoftLayer Services website, we find that the Network_Gateway_Vlan service has a method called createObjects that will associate VLANs to a gateway. We see that the argument the method takes is an array of Network_Gateway_Vlan data type objects. So this example will:

• Get the id of the gateway we want to associate the VLANs to
• Get id values of the VLANs to be associated with the gateway
• Build an array of Network_Gateway_Vlan objects; filling in the local properties of that data type
• Call Network_Gateway_Vlan.createObjects(); giving it that array

pprint.pprint(assocVlans)

SoftLayer Exceptions

You probably noticed that none of the example code had error checking. That's because I was waiting to cover SoftLayer exceptions here. The main SoftLayer API exception class is SoftLayer.exceptions.SoftLayerAPIError, and it has two members: faultCode and faultString. You can catch API errors like this:

import SoftLayer

try: # A sample API call gatewayid = 1 # an id that does not exist gw = client[‘Network_Gateway’].getObject(id=gatewayid, mask=‘id’) except SoftLayer.exceptions.SoftLayerAPIError as e: print ‘SoftLayer exception occurred: ’ + str(e.faultCode) + ‘: ’ + e.faultString

You can see some of the common faultStrings at the bottom of http://sldn.softlayer.com/article/Exception-Handling-SoftLayer-API in case you want to handle some of them individually in the "except" section of your code.

In my next blog post I'll cover in detail how to order SoftLayer resources using the API.