Scribd
Upload
317 views

Slicehost API: April 1, 2008

The document describes the Slicehost API for accessing DNS services programmatically. It provides documentation on authentication, examples of using the API in Ruby and Python, and descriptions of the DNS zone and record resources that can be accessed and modified. The API follows an ActiveResource pattern and uses HTTP authentication with the API password.

Uploaded by

Oleksiy Kovyrin
Copyright
© Attribution Non-Commercial (BY-NC)
Available Formats
Download as PDF, TXT or read online on Scribd
317 views

Slicehost API: April 1, 2008

The document describes the Slicehost API for accessing DNS services programmatically. It provides documentation on authentication, examples of using the API in Ruby and Python, and descriptions of the DNS zone and record resources that can be accessed and modified. The API follows an ActiveResource pattern and uses HTTP authentication with the API password.

Uploaded by

Oleksiy Kovyrin
Copyright
© Attribution Non-Commercial (BY-NC)
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 8

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

You might also like