Slicehost API

Version 1.2 April 1, 2008

Copyright 2008 Slicehost, LLC

Slicehost API
Abstract Introduction Getting Started
Authentication ActiveResource Ruby Example Python Example

3
3 3 3
3 3 4 5

Services
DNS
Zone Record

7
7
7 7

Common Errors

8

Copyright 2008 Slicehost, LLC

Slicehost API
Abstract
The Slicehost API is an interface to Slicehost services, allowing users to automate tasks as needed. The current iteration allows access to DNS only.

Introduction
To use the Slicehost API, you must have a Slicehost account. You may enable or disable API access from this account, and you may re-generate your API password as you see fit. This API follows a standard ActiveResource pattern as seen in Ruby on Rails. The examples in this document are in Ruby, using the Ruby on Rails ActiveResource library.

Getting Started
Authentication Before you can access the API service, you must enable the service in the SliceManager under the Account tab. Note that this automatically generates a unique API password for you. Should you need to update the password, you can generate a new one from the same page at any time. Authentication for the API uses standard HTTP Authentication which uses your unique password as part of the URL. Hereʼs an example:
https://3da541559918a808c2402bba5012f6c60b27661c@api.slicehost.com/

ActiveResource To learn about how to use ActiveResource within Ruby (or to develop a way to do it in another language, we suggest reading the ActiveResource README.

Copyright 2008 Slicehost, LLC

Ruby Example Below is an example of using oneʼs API password in an ActiveResource class to manipulate Zones:
require 'activeresource' API_PASSWORD = "3da541559918a808c2402bba5012f6c60b27661c" class Zone < ActiveResource::Base self.site = "https://#{API_PASSWORD}@api.slicehost.com/" end class Record < ActiveResource::Base self.site = "https://#{API_PASSWORD}@api.slicehost.com/" end # Creating a new Zone myzone = Zone.new(:origin => ‘example.com’, :ttl => 3000) myzone.save # Creating a record for that Zone myrecord = Record.new(:record_type => 'A', :zone_id => 12345, :name => 'www', :data => '127.0.0.1') myrecord.save # Updating the record myrecord.ttl = 55000 myrecord.save # Deleting the record myrecord.destroy # Back to our Zone zid = myzone.id # The ID of the new Zone # Let’s use this to re-retrieve the Zone myzone = nil myzone = Zone.find(zid) # Retrieving the same Zone we just created myzone.ttl = 8000 myzone.save # Updating the TTL myzone.destroy # Destroying the Zone

Copyright 2008 Slicehost, LLC

Python Example Since Python has no ActiveResource library available (yet), we have to build an HTTP request ourselves. We put together a simple APIRequest object to do just that. For more information on whatʼs going on, read through the link in the ActiveResource section. (There is also a beta library called pyactiveresource written by our own Jared Kuolt which you can use as an alternative to the method below.)
import httplib import urllib import base64 class APIRequest(object): def __init__(self, password, object_type, id=None, params={}, method='GET'): self.host = 'api.slicehost.com' self.headers = {'Authorization': 'Basic %s' % base64.encodestring(password)} self.method = method self.object_type = object_type self.object_type_plural = '%ss' % object_type self.params = self.parse_params(params) if id: self.path = '/%s/%s.xml' % (self.object_type_plural, id) else: self.path = '/%s.xml' % self.object_type_plural def parse_params(self, params): assert isinstance(params, dict) np = {} for key, val in params.iteritems(): k = '%s[%s]' % (self.object_type, key) np[k] = val return urllib.urlencode(np) def response(self): conn = httplib.HTTPSConnection(self.host) conn.request(self.method, self.path, self.params, self.headers) return conn.getresponse().read() def main(): pw = 'my-api-password' # GETting all Zones
Copyright 2008 Slicehost, LLC

APIRequest(pw, 'zone').response() # GETting a single Zone APIRequest(pw, 'zone', id=5).response() # Create a new Zone using POST params = {'ttl': 86400, 'origin':'example.com'} APIRequest(pw, 'zone', params=params, method='POST').response() # Updating a Zone using PUT params = {'ttl':12345, 'origin':'example.org'} APIRequest(pw, 'zone', id=zone_id, params=params, method='PUT').response() # Destroying a Zone APIRequest(pw, 'zone', id=zone_id, method='DELETE').response() if __name__ == '__main__': main()

Copyright 2008 Slicehost, LLC

Services
Not all of the services Slicehost provides are accessible via this API, however, we plan to offer as many API services as possible. Fields in bold are required. Note: In addition to all fields outlined below, the `id` field is the identifier of an object which may not be changed.

DNS
DNS is split into two sets of resources: Zones and Records. Zones represent a domain, whereas Records represent the records within a Zone. Zone Field origin ttl active Record Field record_type zone_id rw rw Access Notes Must be a valid record type: A, CNAME, MX, NS, SRV, TXT, AAAA, PTR Must be an id of a Zone owned by the same customer. Note: this may not be changed after creation. Must be a valid name Must be valid data per the record_type Must be an integer and above 60 “Y” or “N” indicating whether Record is active Auxiliary info for the record rw rw rw Access Notes The origin field is the domain name, e.g. “example.com.” Must be an integer and above 60 “Y” or “N” indicating whether Zone is active

name data ttl active aux

rw rw rw rw rw

Copyright 2008 Slicehost, LLC

Common Errors
The following are common error messages and what they mean: HTTP Code 503 Meaning The service is temporarily disabled. This will happen when we perform maintenance; The API service will likely be back online shortly. Unprocessable Entity; The request, or parameters in the request, were malformed. The most common reason for this is an invalid value, e.g. “A” for a Zone TTL. Unauthorized; Your API Password is invalid.

422

401

Copyright 2008 Slicehost, LLC