rackspace-api

A Node.js module to help you interface the Rackspace Cloud API in your code.

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

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

npm install rackspace-api

Clone this repository:

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

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.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

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.

Gets a list of images.

Retrieves the details of the image specified by id.

  • id is the image ID.

Deletes the specified image.

  • id is the image ID.

Gets a list of server flavors.

Retrieves the details of the flavor specified by id.

  • id is the flavor ID.

Gets a list of servers at this endpoint.

Retrieves the details of the server specified by id.

  • id is the server ID.

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

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

Provisions a new OpenStack server.

Updates a server's properties.

  • id is the server ID.

Deletes a server instance.

  • id is the server ID.

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

  • id is the server ID.

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

  • id is the server ID.

Retrieves the details for the specified attached volume.

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

Attaches a block storage volume to the specified server.

  • id is the server ID.

Detaches a block storage volume from the specified server.

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

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

  • id is the server ID.

Sets a metadata item on the specified server.

  • id is the server ID.

Updates a metadata item on the specified server.

  • id is the server ID.

Retrieves a specific metadata item for the specified server.

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

Sets a specific metadata item for the specified server.

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

Deletes a specific metadata item from the specified server.

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

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' }

Returns a list of account details

Retrieves a list of all containers in the account

Gets a full list of details for the container called name

Creates a new container called name

If it's empty, deletes the container called name

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' }

Lists the contents of the container called name

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

Stores data in an object called object in container container

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'.

Deletes the object called object from the container called container.

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

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' }

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

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' }

Lists all containers that are CDN-enabled

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.

Enables CDN availability on the container called container

Disabled CDN availability on container

This exposes the Cloud DNS API.

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

Retrieves limits placed on your Cloud DNS account

Retrieves info about different types of limits on your account

Returns the value of the limit called limit

Gets a list of all of your domains

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

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)

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

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.

Creates the domain(s) specified in data

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

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.

Removes a domain from your Cloud DNS account

Lists all subdomains of the domain with ID domainId

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

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

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

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

Deletes the record specified

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.

Shows the details of a PTR record

Adds a PTR record as defined in data

Modifies an existing PTR record in a manner described in data

Deletes a PTR record from the specified service

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.

Lists all load balancers on the account

Gets the details of the specified load balancer.

Creates the load balancer defined by data

Updates the configuration of a load balancer

Deletes the specified load balancer

Retrieves the contents of the load balancer's error page

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

Removes the error page configuration from the load balancer

Lists load balancer statistics

Lists nodes behind the load balancer

Gets a node's configuration

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

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

Retrieves a log of events that have occurred on all nodes

Lists all IP addresses associated with the load balancer

Lists domains allowed access to the load balancer

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.

Deletes the specified IP address from the specified load balancer.

Gets a list of load balancers in a billable state

Reports overall load balancer usage

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

Reports current usage of a load balancer

Returns the load balancer's access list

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

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

Completely deletes the full access list from the load balancer

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

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

Clears the health monitor config from a load balancer

Retrieves the session persistence configuration for the load balancer

Turns on session persistence

Turns off session persistence

Gets the connection logging status

Enables or disables connection logging

  • enabled - true or false to enable or disable connection logging

Gets the throttling config

Sets the throttling config

Removes all throttling configuration

Retrieves the caching config

Enables or disables content caching

  • enabled - true or false to enable or disable connection logging

Shows protocols supported by load balancers

Shows algorithms supported by load balancers

Gets the SSL termination configuration

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

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(){});

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.

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.

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(){});

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