rackspace-api

rackspace-api is a Node.js module to help you interface the Rackspace Cloud API in your code.

Disclaimer

This is an unofficial library, created without Rackspace's official support.

How to get it

With npm

npm install rackspace-api

With git

Clone this repository:

git clone https://github.com/GradysGhost/node-rackspace-api.git

How to use it

It's still in it's infancy right now, so you shouldn't use this in production. All the same, it should work with a standard require:

var rackApi = require("rackspace-api");

Then get yourself an instance.

var api = new rackApi.Api(username, password, authType, authEndpoint);

username - Your Rackspace Cloud username
password - Depending on the authType value, this should either be your password or API key
authType - Either "api" or "password"; defaults to "password"
authEndpoint - Either "us" or "uk"; defaults to "us"

This will create a new Api object.

Api

api.authenticate(callback)

callback - A callback function taking two arguments:
- jsonContent - The JSON response from the authentication server (see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/auth-response-description.html)
- serviceObjects - An object containing other objects, each one a code object representing a Rackspace Cloud API service endpoint, as described below

The serviceObjects object should contain various instances of the following object types in the form of the type's name in camel case, followed by an ALL-CAPS object representing a data center. For example, to build a server in the DFW data center, you would execute something like...

serviceObjects.cloudServerOpenStackEndpoint.DFW.createServer(data, callback);

Additionally, each of these objects' functions accepts a callback value. That function, in all cases except where noted otherwise, is a response object. That object will contain the following members:

headers - An object representing the HTTP response headers
body - An object containing the API response
error - Only present when an error is returned; contains that error object

CloudServerOpenStackEndpoint

This documentation refers to params and data values frequently. In all cases, refer to the Rackspace Cloud Servers API Documentation. params always refers to options to be passed along with GET requests in the URL query string. data always refers to a stringified JSON object to be passed in the request body.

Furthermore, id variables are often called for. This documentation will list what ID each of those variables needs to be, since it varies, but in all cases, you can get the ID of that object by running the relevant list function. For example, imageDetails needs an image ID, which you can gather by calling the images function first.

images (params, callback)

Gets a list of images.

imageDetails (id, callback)

Retrieves the details of the image specified by id.

id is the image ID.

deleteImage (id, callback)

Deletes the specified image.

id is the image ID.

flavors (params, callback)

Gets a list of server flavors.

flavorDetails (id, callback)

Retrieves the details of the flavor specified by id.

id is the flavor ID.

servers (params, callback)

Gets a list of servers at this endpoint.

serverDetails (id, callback)

Retrieves the details of the server specified by id.

id is the server ID.

serverIPs (id, network, callback)

Retrieves a list of IP addresses associated with a server and network interface.

id is the server ID.
network is the network ID.

createServer (data, callback)

Provisions a new OpenStack server.

updateServer (id, params, data, callback)

Updates a server's properties.

id is the server ID.

deleteServer (id, callback)

Deletes a server instance.

id is the server ID.

serverAction (id, data, callback)

Executes an action on the specified server, such as issuing a reboot or updating the admin password.

id is the server ID.

volumes (id, callback)

Gets a list of the block storage volumes attached to the specified server.

id is the server ID.

volumeDetails (id, attachmentID, callback)

Retrieves the details for the specified attached volume.

id is the server ID.
attachmentID is the volume attachment ID.

attachVolume (id, params, data, callback)

Attaches a block storage volume to the specified server.

id is the server ID.

detachVolume (id, attachmentId, callback)

Detaches a block storage volume from the specified server.

id is the server ID.
attachmentID is the volume attachment ID.

metadata (id, data, callback)

Gets a list of all metadata items for the specified server.

id is the server ID.

setMetadata (id, data, callback)

Sets a metadata item on the specified server.

id is the server ID.

updateMetadata (id, data, callback)

Updates a metadata item on the specified server.

id is the server ID.

getMetadataItem (id, key, callback)

Retrieves a specific metadata item for the specified server.

id is the server ID.
key is the metadata key whose value should be retrieved.

setMetadataItem (id, key, callback)

Sets a specific metadata item for the specified server.

id is the server ID.
key is the metadata key whose value should be set.

deleteMetadataItem (id, key, callback)

Deletes a specific metadata item from the specified server.

id is the server ID.
key is the metadata key whose value should be deleted.

CloudFilesEndpoint

This object lets you access and manipulate Cloud Files containers and their contents. This is true of all containers, regardless of their CDN-enabledness.

In all of the following functions, the params variable is an object full of key/value pairs which will be translated into a query string for the ultimate API call. You can use this to filter the results of many queries, or force an XML response. If you do not force an XML response, these functions will force a JSON response so it can be objectified in the callback. Documentation on how to use this can be found here.

To force an XML response, set params to:

{ 'format' : 'xml' }

accountDetails (callback)

Returns a list of account details

containers (params, callback)

Retrieves a list of all containers in the account

containerDetails (name, callback)

Gets a full list of details for the container called name

createContainer (name, params, callback)

Creates a new container called name

deleteContainer (name, params, callback)

If it's empty, deletes the container called name

setContainerMetadata (name, data, params, callback)

Sets any number of metadata keys on the container called name

data is an object in the form of { 'key1':'value1', 'key2':'value2', ..., 'keyN':'valueN' }

containerList (name, params, callback)

Lists the contents of the container called name

get (container, object, params, callback)

Downloads the file called object in the container called container. Check the response headers for MIME-type info

put (container, object, data, params, callback)

Stores data in an object called object in container container

copy (from, to, params, callback)

Performs a server-side copy of an object and its metadata

from and to are the source and destination objects, respectively, both in the form of 'container/object'. For example, to specify the object image.jpg in the container mywebsite you'd pass 'mywebsite/image.jpg'.

delete (container, object, params, callback)

Deletes the object called object from the container called container.

objectDetails (container, object, params, callback)

Retrieves the full details of the object object in the container container

setObjectMetadata (container, object, data, params, callback)

Sets any number of metadata keys on the object called object in the container container

data is an object in the form of { 'key1':'value1', 'key2':'value2', ..., 'keyN':'valueN' }

CloudFilesCDNEndpoint

This object lets you manage the CDN-specific portions of your Cloud Files content.

To force an XML response, set params to:

{ 'format' : 'xml' }

containers (params, callback)

Lists all containers that are CDN-enabled

containerDetails (container, params, callback)

Retrieves the details of the container called container.

This function is redundant with CloudFilesEndpoint.containerDetails, and is present in its erroneousness for the sake of usability alone.

enable (container, params, callback)

Enables CDN availability on the container called container

disable (container, params, callback)

Disabled CDN availability on container

CloudDNSEndpoint

This exposes the Cloud DNS API.

For valid options to the params and data objects in the following examples, refer to the documentation, please.

limits (callback)

Retrieves limits placed on your Cloud DNS account

limitTypes (callback)

Retrieves info about different types of limits on your account

getLimit (limit, callback)

Returns the value of the limit called limit

domains (params, callback)

Gets a list of all of your domains

domainDetails (domainId, params, callback)

Shows details about the domain with an id (not a domain anme) of domainId

domainChanges (domainId, params, callback)

Lists changes made to the domain with id domainId

It's worth looking at the documentation to learn about the since parameter for this. (Reference)

exportDomain (domainId, callback)

Begins the process of exporting a domain. This produces a Job ID, which you can use to check the status of this asynchronous request.

jobStatus (jobId, params, callback)

Retrieves the status of a job. When the param key called showDetails is 'true' and the status is 'COMPLETED', it returns the request response as well.

createDomain (data, callback)

Creates the domain(s) specified in data

importDomain (data, callback)

Imports the domain from a BIND 9 file, previously exported with exportDomain

modifyDomain (domainId, data, callback)

Uses the object in data to modify a stored domain (or multiple domains)

If domainId is null, the request is processed as a multi-domain edit. Otherwise, specify the Domain ID of the one you wish to modify.

removeDomain (domainId, params, callback)

Removes a domain from your Cloud DNS account

subdomains (domainId, params, callback)

Lists all subdomains of the domain with ID domainId

records (domainId, params, callback)

Gets a list of all records in the domain specified by domainId

recordDetails (domainId, recordId, params, callback)

Shows the details of the record specified by recordId, and which belongs to the domain with ID domainId

addRecord (domainId, data, params, callback)

Adds a record (or some) defined in data to the domain with ID domainId

modifyRecord (domainId, recordId, data, callback)

Modifies a record with ID recordId in domain with ID domainId, as defined by data

removeRecord (domainId, recordId, params, callback)

Deletes the record specified

ptrs (service, params, callback)

Lists PTR records on your account

In the case all five of these PTR functions, the followng two statements are true:

service is a service name like 'cloudServersOpenStack'
params here needs an 'href' key with a service URL. See the API docs.

ptrDetails (service, recordId, params, callback)

Shows the details of a PTR record

addPtr (data, callback)

Adds a PTR record as defined in data

modifyPtr (data, callback)

Modifies an existing PTR record in a manner described in data

removePtr (service, params, callback)

Deletes a PTR record from the specified service

CloudLoadBalancersEndpoint

This object works with Cloud Load Balancers, naturally.

Many of the functions in this library allow you specify more than one object at a time in the URL by passing a repeated id parameter. For context, see the documentation. One example of this can be found in the Remove Metadata documentation, where you can specify multiple metadata IDs. The functions bound to API calls like this (deleteMetadata, in this example) are capable of handling this for you, but also for just specifying a single ID. See the documentation below to see how to work with each case of this.

In all cases, lbId, nodeId, and metaId are the IDs of the load balancer, node, and metadata item to affect. data is an object, the details of which you should verify in the Load Balancer API Documentation. params is an object which will be converted to a query string for the request.

loadBalancers (callback)

Lists all load balancers on the account

loadBalancerDetails (lbId, callback)

Gets the details of the specified load balancer.

createLoadBalancer (data, callback)

Creates the load balancer defined by data

updateLoadBalancer (lbId, data, callback)

Updates the configuration of a load balancer

deleteLoadBalancer (lbId, callback)

Deletes the specified load balancer

errorPage (lbId, callback)

Retrieves the contents of the load balancer's error page

setErrorPage (lbId, content, callback)

Sets the contents of the load balancer's error page to content

deleteErrorPage (lbId, callback)

Removes the error page configuration from the load balancer

stats (lbId, callback)

Lists load balancer statistics

nodes (lbId, callback)

Lists nodes behind the load balancer

nodeDetails (lbId, nodeId, callback)

Gets a node's configuration

addNode (lbId, data, callback)

Adds a node to the load balancer, as described by data

deleteNode (lbId, nodeId, params, callback)

Removes a node from the load balancer configuration. Has no effect on any Cloud Servers the node may represent.

serviceEvents (lbId, callback)

Retrieves a log of events that have occurred on all nodes

ips (lbId, callback)

Lists all IP addresses associated with the load balancer

allowedDomains (callback)

Lists domains allowed access to the load balancer

addIp (lbId, isPublic, callback)

Adds the IP that data describes to the load balancer. Note that this will always produce an IPv6 address.

isPublic - When true, the IP is Internet-facing. Otherwise, it's a ServiceNet IP.

deleteIp (lbId, ipId, params, callback)

Deletes the specified IP address from the specified load balancer.

billableLoadBalancers (params, callback)

Gets a list of load balancers in a billable state

accountUsage (params, callback)

Reports overall load balancer usage

historialLoadBalancerUsage (lbId, params, callback)

Reports usage of a load balancer over time. Use params to control time range.

currentLoadBalancerUsage (lbId, params, callback)

Reports current usage of a load balancer

accessList (lbId, callback)

Returns the load balancer's access list

addNetworkItem (lbId, data, callback)

Adds a network item to the load balancer's access list

deleteNetworkItem (lbId, netItemId, callback)

Removes a network item defined by netItemId from the load balancer's access list

deleteAccessList (lbId, params, callback)

Completely deletes the full access list from the load balancer

healthMonitor (lbId, callback)

Gets the details of the load balancer's health monitor configuration

updateHealthMonitor (lbId, data, callback)

Updates the load balancer's health monitor configuration as described by data

deleteHealthMonitor (lbId, callback)

Clears the health monitor config from a load balancer

sessionPersistence (lbId, callback)

Retrieves the session persistence configuration for the load balancer

enableSessionPersistence (lbId, callback)

Turns on session persistence

disableSessionPersistence (lbId, callback)

Turns off session persistence

connectionLogging (lbId, callback)

Gets the connection logging status

setConnectionLogging (lbId, enabled, callback)

Enables or disables connection logging

enabled - true or false to enable or disable connection logging

throttle (lbId, callback)

Gets the throttling config

updateThrottle (lbId, data, callback)

Sets the throttling config

deleteThrottle (lbId, callback)

Removes all throttling configuration

contentCaching (lbId, callback)

Retrieves the caching config

setContentCaching (lbId, enabled, callback)

Enables or disables content caching

enabled - true or false to enable or disable connection logging

protocols (callback)

Shows protocols supported by load balancers

algorithms (callback)

Shows algorithms supported by load balancers

termination (lbId, callback)

Gets the SSL termination configuration

updateTermination (lbId, data, callback)

Sets the SSL termination config to what's described in data

metadata (lbId, metaId, nodeId, callback)

Retrieves metadata associated with the specified resource(s).

This function can get metadata for a single load balancer or node, or multiple load balancers or nodes. Here's a list of things you can do and how to do it, but you should refer to the documentation to understand the hows and whys:

Retrieve metadata for a single load balancer with ID 42:

metadata('42', null, null, function(){});

Get details for a specific load balancer metadata object:

metadata('41', '2', null, function(){});

Get a list of metadata objects associated with a particular node behind a load balancer:

metadata('41', null, '3', function(){});

Get details for a specific node's metadata object

metadata('41', '2', '3', function(){});

addMetadata (lbId, nodeId, data, callback)

Adds metadata from data to a load balancer or a node behind one

To add metadata to a load balancer, set nodeId to null. To add it to a node, specify both a lbId and nodeId.

updateMetadata (lbId, metaId, nodeId, data, callback)

Updates the metadata on a load balancer or node

To update a load balancer's metadata, set nodeId to null. To update a node's metadata, provide a nodeId. To specify which metadata object, also supply a metaId.

deleteMetadata (lbId, metaId, nodeId, params, callback)

Deletes metadata associated with a load balancer or node

To delete a single metadata object from a load balancer, provide a metaId, but leave nodeId set to null.
To delete a single object from a node, provide both a metaId and a nodeId.
To delete multiple metadata objects from a load balancer, set metaId and nodeId to null. Also stick an array called id in params like in the example below.
To delete multiple objects from a node, provide a nodeId, but a null metaId. Put an array called id in params like in the example below.

The following example shows how to delete multiple metadata objects from a load balancer at once:

deleteMetadata('42', null, null, {'id':[metaId1, metaId2, metaIdN]}, function(){});

Work In Progress

There is more to come with this, but as stated above, this is still in very early development.