Slicehost API
Version 1.2
April 1, 2008
Copyright 2008 Slicehost, LLC
Slicehost API
3
Abstract
3
Introduction
3
Getting Started
3
Authentication
3
ActiveResource
3
Ruby Example
4
Python Example
5
Services
7
DNS
7
Zone
7
Record
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://[email protected]/
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 Access Notes
origin rw The origin field is the domain name, e.g.
“example.com.”
ttl rw Must be an integer and above 60
active rw “Y” or “N” indicating whether Zone is active
Record
Field Access Notes
record_type rw Must be a valid record type: A, CNAME, MX,
NS, SRV, TXT, AAAA, PTR
zone_id rw Must be an id of a Zone owned by the same
customer. Note: this may not be changed after
creation.
name rw Must be a valid name
data rw Must be valid data per the record_type
ttl rw Must be an integer and above 60
active rw “Y” or “N” indicating whether Record is active
aux rw Auxiliary info for the record
Copyright 2008 Slicehost, LLC
Common Errors
The following are common error messages and what they mean:
HTTP Code Meaning
503 The service is temporarily disabled. This will happen when we
perform maintenance; The API service will likely be back
online shortly.
422 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.
401 Unauthorized; Your API Password is invalid.
Copyright 2008 Slicehost, LLC
