Rackspace Cloud Feeds™ API enables customers on the public cloud to access
near real-time usage and system events that can be used for analysis,
monitoring, and automation through a simple Representational State Transfer
(REST) web service interface.

Protect your API key. Do not expose the value in code samples, screen
captures, or insecure client-server communications. Also, ensure that
the value is not included in source code that is stored in public
repositories.

cURL is a command-line tool that you can use to interact with REST interfaces. cURL lets
you transmit and receive HTTP requests and responses from the command line or a shell
script, which enables you to work with the API directly. cURL is available for Linux
distributions, Mac OS® X, and Microsoft Windows®. For information about cURL, see
http://curl.haxx.se/.

To run the cURL request examples shown in this guide, copy each example from the HTML version
of this guide directly to the command line or a script.

Important

The cURL examples in this guide are provided for reference only. Because
the use of cURL has environmental dependencies, copying and pasting the
examples might not work in your environment.

The following example shows a cURL command for sending an authentication request to
the Rackspace Identity service.

In this example, $apiKey is an environment variable that stores your API key value.
Environment variables make it easier to reference account information in API requests,
to reuse the same cURL commands with different credentials, and also to keep sensitive
information like your API key from being exposed when you send requests to Rackspace
Cloud API services. For details about creating environment variables, see Configure
environment variables.

Note

The carriage returns in the cURL request examples use a backslash (\) as an
escape character. The escape character allows continuation of the command across
multiple lines.

The cURL examples in this guide use the following command-line options.

Option

Description

-d

Sends the specified data in a POST request to the HTTP server.
Use this option to send a JSON request body to the server.

-H

Specifies an extra HTTP header in the request. You can specify any
number of extra headers. Precede each header with the -H option.

Common headers in Rackspace API requests are as follows:

Content-Type: Required for operations with a request body.

Specifies the format of the request body. Following is the syntax
for the header where format is json:

Content-Type:application/json

X-Auth-Token: Required.

Specifies the authentication token.

X-Auth-Project-Id: Optional.

Specifies the project ID, which can be your account number or
another value.

Accept: Optional.

Specifies the format of the response body. Following is the syntax
for the header where the format is json, which is the
default:

Accept:application/json

-i

Includes the HTTP header in the output.

-s

Specifies silent or quiet mode, which makes cURL mute. No progress or
error messages are shown.

-T

Transfers the specified local file to the remote URL.

-X

Specifies the request method to use when communicating with the HTTP
server. The specified request is used instead of the default method,
which is GET.

For commands that return a response, use json.tool to pretty-print the output by
appending the following command to the cURL call:

To make calls against the Cloud Feeds API by using an authentication
token, you must first generate an authentication token. You provide this
token in the X-Auth-Token header in each Cloud Feeds API request.

The examples in the Getting Started Guide show how to get an authenticate by
using username and API key credentials, which is a more secure way to communicate
with API services. The authentication token operations reference describes other
types of credentials that you can use for token-based authentication.

If your credentials are valid, the Identity service returns an authentication response
that includes the following information:

an authentication token

a service catalog with information about the services you can access.

user information and role assignments

In the following example, the ellipsis (...) represents other service endpoints, which
are not shown. The values shown in this and other examples vary because the information
returned is specific to your account.

{"access":{"token":{"id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","expires":"2014-11-24T22:05:39.115Z","tenant":{"id":"110011","name":"110011"},"RAX-AUTH:authenticatedBy":["APIKEY"]},"serviceCatalog":[{"name":"cloudDatabases","endpoints":[{"publicURL":"https://syd.databases.api.rackspacecloud.com/v1.0/110011","region":"SYD","tenantId":"110011"},{"publicURL":"https://dfw.databases.api.rackspacecloud.com/v1.0/110011","region":"DFW","tenantId":"110011"},{"publicURL":"https://ord.databases.api.rackspacecloud.com/v1.0/110011","region":"ORD","tenantId":"110011"},{"publicURL":"https://iad.databases.api.rackspacecloud.com/v1.0/110011","region":"IAD","tenantId":"110011"},{"publicURL":"https://hkg.databases.api.rackspacecloud.com/v1.0/110011","region":"HKG","tenantId":"110011"}],"type":"rax:database"},...{"name":"cloudDNS","endpoints":[{"publicURL":"https://dns.api.rackspacecloud.com/v1.0/110011","tenantId":"110011"}],"type":"rax:dns"},{"name":"rackCDN","endpoints":[{"internalURL":"https://global.cdn.api.rackspacecloud.com/v1.0/110011","publicURL":"https://global.cdn.api.rackspacecloud.com/v1.0/110011","tenantId":"110011"}],"type":"rax:cdn"}],"user":{"id":"123456","roles":[{"description":"A Role that allows a user access to keystone Service methods","id":"6","name":"compute:default","tenantId":"110011"},{"description":"User Admin Role.","id":"3","name":"identity:user-admin"}],"name":"jsmith","RAX-AUTH:defaultRegion":"ORD"}}}

If the request was successful, you can find the authentication token and other information in the
authentication response. You'll need these values to submit requests to the API. See
Configure environment variables.

If the request failed, review the response message and
the following error message descriptions to determine next steps.

The authentication response returns the following values that you
need to include when you make service requests to the Rackspace Cloud Feeds API.

token ID

The token ID value is required to confirm your identity each time you access the service.
Include it in the X-Auth-Token header for each API request.

The expires attribute indicates the date and time that the token will expire,
unless it is revoked prior to the
expiration. To get a new token, submit another authentication request. For more
information, see
Manage tokens and token expiration.

tenant ID

The tenant ID provides your account number. For most Rackspace Cloud service APIs, the
tenant ID is appended to the API endpoint in the service catalog automatically.

endpoint

The endpoint provides the URL that you use to access the API service. For guidance
on choosing an endpoint, see Service access.

To make it easier to include the values in API requests, use the export command to create
environment variables that can be substituted for the actual values. For example, you can
create an ENDPOINT variable to store the URL for accessing an API service.
To reference the value in an API request, prefix the variable name with a $, for example
$ENDPOINT.

Note

The environment variables created with the export command are
valid only for the current terminal session. If you start a new session, run the
export commands again.

To reuse the variables across sessions, update the configuration file for your shell
environment to include the export statements. For details
about using and managing environment variables on different systems, see the
Environment variables wiki.

To make a request to the Cloud Feeds API with basic authentication, you
need to issue a cURL call directly against the requested end point by
providing the username and API key directly in the call as shown here:

curl-u<username:api-key>-X<method>https://endpointURL/

The following example shows how to retrieve the feeds catalog by using
basic authentication:

To use Cloud Feeds you need to have a basic understanding of REST APIs. This section
describes how to use the Cloud Feeds REST API to perform basic API operations.

Important

This section assumes that you are using token-based authentication and
that you have successfully authenticated against the Rackspace Cloud API
and obtained an authentication token as described in
token authentication.

A successful response to a GET request to obtain a feed returns links that help you navigate
to the Atom entries in the feed. The following links are returned in the Cloud Feeds responses:

Use the current link node to go to the current feed.

Use the last links to go to the last page of Atom entries in the database for the
specified feed. Using the last link can be useful for finding the first Atom for
a given feed. Note that Cloud Feeds uses a mock last link marker. This helps move
some of the heavier queries off the feed head call.

Use the self link to bring back the entry that you are currently viewing. If the
feeds are being hit with no options, any new Atom entries have been entered,
then those entries also appear.

Use the next link to navigate by page to the next page of Atom entries. When you get
to the end of the feed, this link is no longer present.

Use the previous link to navigate by page to the previous page of Atom entries.
Sometimes the link is in the feed header; however, the link is not be in the feed
header if the feed is empty. If you are at the top of the feed and you follow this
link, an empty feed is returned unless new entries have occurred since you last
polled. In a feed, the entries are shown in order from newest to oldest.

The following diagram shows how pagination works with Cloud Feeds:

Important

When viewed in a web browser or web tool such as Chrome Poster, each & character in
a link returns as an HTML ampersand character code. To follow the link in a web
browser or web tool such as Poster, you must change each HTML ampersand character
(&amp;) to &. For example, when viewed in a web browser, the feed returns the
following link.

You can use query parameters to customize the entries and their order
within a feed. Query parameters are part of the URL that is passed to
the server as part of an API request. When you add query parameters to
an API request, you modify the results in specific ways, such as
refining your query or sorting the output.

A typical URL that contains a query parameter looks like the following
URL:

http://server/program/path/?query_string

The query string is composed of one or more field value pairs that use
the following format:

Within each field value pair, the field name and value are separated
by an equals sign (=).

Pairs in series are separated by ampersand (&), as shown in the
following example:

field1=value1&field2=value2&field3=value3...

The following table summarizes the query parameters you can specify for
Cloud Feeds.

Query parameters

Query
parameter

Description

Acceptable values

marker

Specifies a UUI that
exists in the Cloud
Feeds system.

Must be a valid UUI that exists in
the Cloud Feeds system, for example
rn:uuid:cd42141b-c030-6fca-6704-8285789a274b.
This parameter can also be set to
last. If this parameter is set
to last, Cloud Feed locates a
page that contains the oldest entry
in the feed.

direction

Specifies the direction
from which to return
entries, starting from
the current marker or
entry.

Can be either forward or
backward.

limit

Specifies the number of
entries to be returned.
If the entered limit is
greater than the actual
number of entries, the
actual number of entries
is used.

You can use the marker parameter to denote an entry that you have
previously used. If you specify a marker in the GET request, you can
also specify a value for the direction parameter. If you do not
specify a value for the direction parameter, the default value of
forward is used.

The following example shows a marker parameter specified and the
direction parameter set to forward:

You can use a GET request to filter for certain types of events you
want to obtain from a feed by defining a specific search category. You
specify the search categories by adding search as the URL parameter
at the end of the feeds URL and then specifying the category or item for
which you want to search. The following example shows how to get all
event types that fall under the cloudsites.metered.site.usage category:

You can use the startingAt query parameter to filter for feed
entries that start at a certain time stamp. The parameter takes an ISO
8601 Date and Time format and must contain a timezone, such as such as 2014-03-10T06:00:00.000Z.

The following URL shows how to fetch entries with a time stamp that is
newer than 2014-03-10 00:00:00.000 UTC:

The startingAt parameter can not be used together with the
marker parameter.

If the startingAt parameter is used without a direction
parameter, then the forward direction is assumed. If you want to fetch
feeds from a time period before the time specified in the time stamp,
you need to use the direction parameter and then the backward
description, like the following: direction set to backward.

Cloud Feeds supports weak entity tags (ETags). An ETag identifies a
specific feed version. When the content of the feed changes, a different
ETag is assigned. ETags provide an efficient way of checking whether a
previously processed feed has changed. Weak ETags are sent back in the
HTTP header with a name of ETag.

Following is an example of weak ETag for a feed that contains more than
one Atom entry:

W/"4ec07c96e1399298d48db885c014703b"

ETags are not returned in the following situations:

The feed is empty.

You use the marker parameter, specify the direction as
forward, and no entries exist after that marker.

The following list describes a number of best practices consumers can adhere to when
reading a feed.

Walk the feed forward

When reading a feed you get the best performance if you start from the last entry
that was successfully read and then walk the feed forward, towards the head of the
feed. Use the following format, substituting the values for <endpoint>, <feed>, and
<uuid_of_last_read_entry>.

The fewer calls to Cloud Feeds, the less processing has to be done. Cloud Feeds
allows you to read up to 1000 entries at a time using the limit query
parameter. Use the following format (along with the recommended direction parameter),
substituting the values for <endpoint>, <feed>, and
<uuid_of_last_read_entry>.

Having Cloud Feeds compress its message body can decrease response time, especially
when you interact with an endpoint in a remote data center. By adding the following
header to your request, you are instructing Cloud Feeds to compress the output. Your
HTTP client uncompresses the output before you read the message body:

``Accept-Encoding: gzip, deflate``

Use high-performance categories when using the search query parameter.

When filtering a feed with the search query parameter, two category types provide
better performance than others, especially for cases when the searched-for category is
rare in the feed.

Category prefixes

Category
prefix

Description

Example

tid:

Specifies the tenant ID, taken
from the tenantid attribute from
the event node.

This guide is intended to assist software developers who want to develop applications by
using the REST application programming interface (API) for the Rackspace Cloud Feeds
service.

To use the information provided here, you should have a general understanding of the
Cloud Feeds service and have access to a Rackspace Cloud account that has access to the
service. You should also be familiar with following technologies:

Cloud Feeds uses AtomPub to publish different types of feeds. Feeds are
composed of a number of items called entries. Each entry has an
extensible set of attached metadata.

AtomPub together with the Atom Syndication Format (ASF) provides a
format for implementing web feeds. Web feeds provide users with
frequently updated content. AtomPub is based on an HTTP transfer of
Atom-formatted representations. The Atom format is documented in the
Atom Syndication Format.

Cloud Feeds is an open-source AtomPub server for accessing, processing,
and aggregating Atom entries. Cloud Feeds was designed to make it easy
to build both generalized and specialized persistence mechanisms for
Atom XML data, based on the Atom Syndication Format and the Atom
Publishing Protocol.

Cloud Feeds works the following way:

Events are generated by a publisher and added to the database as
entries. Events can be usage events, system events or billing events.

Entries exist in Cloud Feeds for three days. After that time period
they are deleted.

To read the official documentation for the Atom Syndication Format, see
RFC 4287. For more information about AtomPub, click here.

An Atom feed element is a representation of an Atom feed, including
metadata about the feed, and some or all of the entries associated with
it.

The Atom Feed element represents the top-level element of an Atom Feed
Document. It functions as a container for metadata and data associated
with the feed. Its element children consist of metadata elements that
are followed by zero or more Atom Entry child elements.

The following example shows an entire Atom feed element in XML format.

The Atom entry element represents exactly one Atom entry, outside of
the context of an Atom feed. It functions as a container for metadata
and data associated with the entry. This element can appear as a child
of the Atom feed element, or it can appear as the top-level element
of a stand-alone Atom Entry Document.

Optional. Specifies the data center of the event.
If this attribute is not specified, GLOBAL is
assumed. GLOBAL implies that the resource is
without an assigned data center.

endTime

Optional. Specifies the time that the event ends.
The format must be ISO 8601 format:
yyyy-mm-ddThh:mm:ss.SSSZ (Z designates UTC). For
an event of type EXIST, the startTime and
endTime reflect the event duration for the
resource instance. The end time is exclusive —
that is, the event occurred up to, but not during
the specified value. The end time must occur after
the start time.

environment

Specifies the environment from which the message
originated. If this attribute is not specified,
PROD is assumed. This attribute is required
for events of type USAGE_SNAPSHOT, but is
optional for all other event types.

eventTime

Optional. Specifies the time of the event, using
ISO 8601 format and UTC. Use this attribute
instead of startTime and endTime in cases
where the event does not have a range.

id

Required. Specifies the UUID for the event record.
This value should be UUID version 1, 2, or 4. For
more information, see RFC 4122.

referenceId

Optional. Specifies a GUID that identifies the
event record that this record is updating. This
attribute should be used if this event is
correcting another event.

region

Specifies the region in which the event is
located. If this attribute is not specified,
GLOBAL is assumed. GLOBAL implies that the
resource is without an assigned region.

resourceId

Specifies the ID of the resource. This attribute
is required if the resourceType attribute is
specified in the product node, but is optional
otherwise.

resourceName

Optional. Specifies the customer-defined name of
the resource.

resourceURI

Optional. Specifies a URI that uniquely identifies
the resource.

rootAction

Optional. Specifies the action that caused the
event.

severity

Optional. Specifies the severity of the event.
Valid values are INFO, WARNING, and
CRITICAL. This is attribute is valid only for
system events, not for usage events.

startTime

Specifies the time that the event starts. The
format must be ISO 8601 format:
yyyy-mm-ddThh:mm:ss.SSSZ (Z designates UTC). The
start time is inclusive, which means that the
event occurred starting at the start time, not
after. This attribute is required for events of
type USAGE, but is optional for all other
event types.

tenantId

Optional. Specifies the tenant Id of the feeds
publisher

type

Required. Specifies the type of event. If one of
the existing event types fails to produce any
feeds, set this attribute to EXTENDED and add
an eventType attribute to your product schema.

Cloud Feeds supports the Cloud Auditing Data Federation (CADF) standard.
CADF provides a standard for the submission and retrieval of normative
audit event data from cloud providers in the form of customized reports
and logs.

The following table shows the CADF nodes that are specified in cadf.xsd.

Table: Elements of the CADF event node

Name

Description

event

Specifies the CADF event node. Contains a
set of attributes. For a detailed
description of the CADF event attributes,
see the “Attributes for CADF event node”
table below.

initiator

Specifies the CADF event initiator.
Contains a set of attributes. For a
detailed description of the CADF initiator
attributes, see the “Attributes for CADF
initiator node” table below.

target

Specifies the target. Contains a set of
attributes. For a detailed description of
the CADF target attributes, see the
“Attributes for CADF target node” table
below.

attachments

attachment

Specifies an array of extended or
domain-specific information about the
node contains one or more nodes of type
of the CADF event attributes, see the
“Attributes for CADF target node” table
below.

observer

Specifies the observer. For example, this
can be a security provider or a service,
such as Repose. Contains a set of
attributes. For a detailed description of
the CADF event attributes, see the
“Attributes for CADF observer node” table
below.

reason

Contains a domain-specific reason code and
policy data that provides an additional
level of detail to the outcome value.
Contains a set of attributes. For a
detailed description of the CADF event
attributes, see the “Attributes for CADF
reason node” table below.

The CADF events are located inside the CADF event node.

The following table shows the elements of the CADF event node.

Table: Elements of the CADF event node

Element/Attribute

Description

id

Required. Specifies the identifier for the
resource.

eventType

Required. Specifies the purpose for creating the
audit record. Must be set to the value
activity.

Required. Specifies the time the event occurred or
began as seen by the observer.

action

Required. Specifies the type of activity that is
described in the event record. Must be set to
read.\*\|create.\*

outcome

Required. Specifies the outcome or result of the
attempted action. Can be either success or
failure.

The following table shows the elements of the CADF initiator node.

Table: Elements of the CADF initiator node

Element/Attribute

Description

id

Required. Specifies the identifier for the
resource.

typeURI

Required. Specifies the type of the resource that
is using the CADF Resource Taxonomy. Can have one
of the following values:

service/security/account/user for authorized
requests

network/node for unauthorized requests

name

Specifies the name of the resource.

host

Specifies the host. Takes one of the following 2
attributes:

address

agent

The following table shows the elements of the CADF target node.

Table: Elements of the CADF target node

Element/Attribute

Description

id

Required. Specifies the identifier for the
resource.

typeURI

Required. Specifies the type of the resource that
is using the CADF Resource Taxonomy. Can have one
of the following values:

service/security/account/user for authorized
requests

network/node for unauthorized requests

name

Specifies the name of the target.

host

Specifies the host. Takes the following attribute:

address

The following table shows the elements of the CADF attachment node.

Table: Elements of the CADF attachment node

Element/Attribute

Description

name

Specifies the name of the attachment, for example
auditData.

contentType

Specifies the content type, for example
ua:auditData.

content

Contains a set of elements that define the
auditData property. auditData contains
attributes that define the user access event
profile for Cloud Feeds. For a detailed
description of the auditData property, see the
“Attributes for auditData property” table in
User access events in Cloud Feeds.

The following table shows the elements of the CADF observer node.

Table: Elements of the CADF observer node

Element/Attribute

Description

id

Required. Specifies the identifier for the
resource.

typeURI

Required. Specifies the type of the resource that
is using the CADF Resource Taxonomy. Can have one
of the following values:

service/security/account/user for authorized
requests

network/node for unauthorized requests

name

Specifies the name.

host

Specifies the host. Takes the following attribute:

address

The following table shows the elements of the CADF reason node.

Table: Elements of the CADF reason node

Element/Attribute

Description

reasonType

Specifies the reason type. For example, this can
be a URL to a HTTP status code registry, such as
RFC 7231.

reasonCode

Required. Specfies the HTTP status code. Can be
one of the following values: "[1-5] [0-9][0-9]".

Cloud Feeds extends the CADF standard by providing a specific user
access event profile that captures audit data that is specific to the
user and the Rackspace cloud services they are using.

User access event data is included in the atom entry as a CADF
attachment of type auditData.

The following table shows the elements of the auditData property.

Table: Elements of the auditData property

Element/Attribute

Description

version

Required. Specifies the version of the audit
data.

region

Required. Specifies the region, such as DFW. If
this value is not specified, GLOBAL is assumed.

dataCenter

Required. Specifies the data center of the
event. If this value is not specified, GLOBAL is
assumed. If this value is set, the region value
must match, for example, if dataCenter is set to
"DFW1," then region must be set to "DFW."

methodLabel

Optional. Specifies the method that is used for
this request. This attribute uses the friendly
name of an API request, for example addUser.

requestURL

Specifies the URI of the request. If the URI
contains any query strings, they truncated.

queryString

Optional. Specifies the query string. The query
string is part of a URI and contianes the data
that was added to the base URI, for example
/?query_string.

tenantId

Specifies the tenant id.

responseMessage

Specifies the response message that is sent as a
response, to the request, for example "CREATED".

The Cloud Feeds API is defined as a RESTful HTTP service that uses all aspects of the
HTTP protocol, including methods, URIs, media types, and response codes. Like other
products in the Rackspace Cloud suite, the Cloud Feeds service shares a
common token-based authentication system that enables seamless access across products
and services.

Review the topics in this section to learn more about these API components and how to access
and use the API for this service.

Note

All requests to authenticate against and operate the service are
performed by using SSL over HTTP (HTTPS) on TCP port 443.

The Rackspace Cloud Feeds service is a regionalized service.
The user can choose the Cloud Feeds endpoint in a specific region to coordinate
the appropriate replication, caching, and overall
maintenance of Cloud Feeds data across regional boundaries to other
Cloud Feeds servers.

Note

For more information about regions, see the About regions
article in the Rackspace How To collection.

The Identity Service catalog returned in response to a successful authentication
request includes a link to the Cloud Feeds service catalog. The Cloud Feeds service
catalog lists all available feeds.

Regionalized service endpoints

Region

Endpoint

Chicago (ORD)

https://ord.feeds.api.rackspacecloud.com/

Dallas/Fort Worth (DFW)

https://dfw.feeds.api.rackspacecloud.com/

Northern Virginia

https://iad.feeds.api.rackspacecloud.com/

London (LON)

https://lon.feeds.api.rackspacecloud.com/

Sydney (SYD)

https://syd.feeds.api.rackspacecloud.com/

Hong Kong (HKG)

https://hkg.feeds.api.rackspacecloud.com/

Note

Choose the endpoint for the data center where your cloud resources
are located.

The cloud server that you use must be located in the same data center
where your database resides.

All examples in this guide assume that you are operating against the
DFW data center. If you are using a different datacenter, be sure to
use the associated endpoint from the table instead.

The endpoints provided in this sections are the base URL for
accessing Cloud Feeds. To access actual feeds, you need to provide
additional information.

Role Based Access Control (RBAC) restricts access to the capabilities of
Rackspace Cloud services, including the Cloud Feeds API, to authorized
users only. RBAC enables Rackspace Cloud customers to specify which
account users of their Cloud account have access to which Cloud Feeds
API service capabilities, based on roles defined by Rackspace.

HTTP/1.1400BadRequestContent-Type:application/json{"title":"Unsupported limit","description":"The given limit cannot be negative, and cannot be greater than 50.","code":1092,"link":{"rel":"help","href":"http://docs.example.com/messages#limit","text":"API documentation for the limit parameter"}}

To reduce the load on the service, list operations return a maximum of
25 entries at a time. However, you can use the limit parameter in
the GET request to allow up to 1,000 entries per page. Specifying
the number of entries to return is referred to as pagination. If a
request supplies no limit or one that exceeds the configured default
limit, the default value is used instead.

Pagination provides the ability to limit the size of the returned data
and retrieve a specified subset of a large data set. Pagination has the
following key concepts: limit and marker.

Limit is the restriction on the maximum number of items for that
type that can be returned.

Marker is the ID of the last item in the previous list returned.
For example, a query could request the next 10 instances after the
instance 1234 as follows: ?limit=10&marker=1234. Items are
displayed sorted by ID.

If the content returned by a request is paginated, the response includes
a structured link with the basic structure
{"href":"<url>","rel":"next"}. Any
response that is truncated by pagination will have a next link, which
points to the next item in the collection. If there are no more items,
no next link is returned.

Cloud Feeds supports archiving of events. Normally, an event remains in
the database for three days. Archiving enables customers to permanently
store events in a Cloud Files container, and to retrieve them from that
location.

Cloud Feeds archives a user's events based on region by storing the data
in the Cloud Files container in a particular region.

Users can elect to have their events stored in one or more of their
Cloud Files containers.

During the archiving process, events are written to files and are
organized by date, feed and region.

Files are formatted as a static feed page for a single day for a single
feed in a region. Users can walk through their archived feeds similarly
to regular feeds by using next-archive and prev-archive links
that point to the next and previous days.

Cloud Feeds provides three options for routing the archiving data to
be stored:

Store all data at a default location, which is specified as one
default container URL.

Store the data dependent on a specified region. For example, an event
originating from the LON region is stored in a Cloud Files container
in LON, an event originating from the SYD region is stored in a Cloud
Files container in SYD, etc. This option requires the user to specify
an archive container URL for each region. Events can also be
configured to be stored in any arbitrary region.

Store some of the data at the default location, and some of the data
at a specific, region-based container URL.

You can configure the following settings for Cloud Feeds archiving:

Enable or disable archiving.

Define the default container for events.

Specify specific containers per region. Any events from an
unspecified region are archived in the default container.

Define format to use for archiving the events: An array of XML, JSON,
or both.

Note

The daily feed archive contains the events that were posted during that
day. The daily feed archive might also list events that contain data
pertaining to days other than the day when the event was posted.

Use the Archiving Configuration API to retrieve and upload archive settings for Cloud
Feeds. This section describes the elements, service endpoint, and RBAC roles for the
Archiving Configuration API. See the Cloud Feeds API operations reference for details.
about the Archive Configuration API operations.

Required. If this value is set to true, archiving is enabled. If set to false, archiving
is disabled.

data_format

Required. Specifies the data format, in which the events are archived. Valid formats are XML
and JSON. Users can select both formats. This parameter is an array.

default_archive_container_url

Optional. Specifies the container URL that is used for archiving Cloud Feeds events.
If this value is set, all Cloud Feeds events from all regions will be archived to this
container.

If this value is not set, one or more archive container URLs must be specified. This
value can be overridden by archive_container_URLs.

archive_container_urls

Optional. Specifies a list of Cloud Files URLs for each region. Each event is archived to the
container that corresponds to its region. You can define container URLs for the following
regions: iad, ord, dfw, lon, hkg, syd. Any events from a region
that do not have a container URL specified will be archived to the default container
URL.

If this value is not specified, then the default container URL must be specified. If
this value is set, you must define at least one region-specific container URL.

The RBAC roles for the Archiving Configuration API differ from the RBAC
roles for the Cloud Feeds API. The main difference is in the
cloudfeeds:service-admin role. Users who are assigned the
cloudfeeds:service-admin role cannot issue GET or POST requests
on multiple tenants but only on a single tenant.

To access archived files from a Cloud Files container requires specified RBAC roles to
be set. Two roles (admin and observer) can be used to access the Cloud Files API
specifically. The following table describes these roles and their permissions.

Table: Cloud Files product roles and permissions

Role

Description

object-store:admin

This role provides create,
read, update, and delete
permissions in Cloud
Files, where access is
granted.

object-store:observer

This role provides read,
permission in Cloud Files,
where access is
granted.

Additionally, two multiproduct roles apply to all products. Users with multiproduct
roles inherit access to future products when those products become RBAC-enabled. The
following table describes these roles and their permissions.

Table: Multiproduct roles and permissions

Role

Description

admin

This role provides create,
read, update, and delete
permissions in all
products, where access is
granted.

observer

This role provides read,
permission in Cloud Files,
where access is
granted.

The Archiving Configuration API only supports token-based
authentication. It does not support basic authentication.

When you configure the Cloud Files container to store events, you have several options.

Single container

If you want to specify one single container URL to store all events,
regardless of which region they originate from, set the
default_container_URL parameter to a valid URL from your Cloud Files
account, as shown in the following example:

If you want to specify a specific container URL for each region, so
that Cloud Feeds routes all the events to be archived to a container
that corresponds with the region of the event, use the
archive_container_urls parameter. For each region, point to a valid
URL from your Cloud Files account that you want the events to be routed
to, as shown in the following example:

Cloud Files also provides the option to specify a default container URL
and one or more archive container URLs. In this configuration, all feeds
that are configured for a region-specific container URL are routed to
that URL. All other feeds are routed to the default container URL. The
following example shows a configuration that routes the feeds from
lon, syd, and hkg to a region-specific URL. All other feeds
are routed to the default container URL.

In addition, archived feeds have an additional node that denotes the
feed as an archive. The archive node is a sub-node of the feed
node that is located at the top of each feed. It uses the following
format:

{"feed":{"@type":"http://www.w3.org/2005/Atom","archive":"","entry":[{"category":[{"term":"tid:5821027"},{"term":"rgn:ORD"},{"term":"dc:ORD1"},{"term":"rid:ed3f75f5-bd98-4c62-b670-46c7d15ea601"},{"term":"widget.widget.gadget.usage"},{"term":"type:widget.widget.gadget.usage"}],"content":{"event":{"@type":"http://docs.rackspace.com/core/event","dataCenter":"ORD1","endTime":"2015-01-25T15:51:11Z","environment":"PROD","id":"59085a27-f9ac-44f7-a74b-0d41fe3c4585","product":{"@type":"http://docs.rackspace.com/usage/widget","label":"test","metaData":{"key":"foo","value":"bar"},"mid":"e9a67860-52e6-11e3-a0d1-002500a28a7a","mixPublicPrivateAttributes":{"myAttribute":"here it should be public","privateAttribute3":"45"},"myAttribute":"here it should be private","privateAttribute1":"something you can not see","privateAttribute3":"W2","resourceType":"WIDGET","serviceCode":"Widget","version":"3","widgetOnlyAttribute":"bar"},"region":"ORD","resourceId":"ed3f75f5-bd98-4c62-b670-46c7d15ea601","startTime":"2012-03-12T11:51:11Z","tenantId":"5821027","type":"USAGE","version":"1"}},"id":"urn:uuid:59085a27-f9ac-44f7-a74b-0d41fe3c4585","published":"2015-01-25T20:59:53.836Z","updated":"2015-01-27T15:16:12.247Z"},{"category":[{"term":"tid:5821027"},{"term":"rgn:ORD"},{"term":"dc:ORD1"},{"term":"rid:ed3f75f5-bd98-4c62-b670-46c7d15ea601"},{"term":"widget.widget.gadget.usage"},{"term":"type:widget.widget.gadget.usage"}],"content":{"event":{"@type":"http://docs.rackspace.com/core/event","dataCenter":"ORD1","endTime":"2015-01-25T15:51:11Z","environment":"PROD","id":"59085a27-f9ac-44f7-a74b-0d41fe3c4585","product":{"@type":"http://docs.rackspace.com/usage/widget","label":"test","metaData":{"key":"foo","value":"bar"},"mid":"e9a67860-52e6-11e3-a0d1-002500a28a7a","mixPublicPrivateAttributes":{"myAttribute":"here it should be public","privateAttribute3":"45"},"myAttribute":"here it should be private","privateAttribute1":"something you can not see","privateAttribute3":"W2","resourceType":"WIDGET","serviceCode":"Widget","version":"3","widgetOnlyAttribute":"bar"},"region":"ORD","resourceId":"ed3f75f5-bd98-4c62-b670-46c7d15ea601","startTime":"2012-03-12T11:51:11Z","tenantId":"5821027","type":"USAGE","version":"1"}},"id":"urn:uuid:59085a27-f9ac-44f7-a74b-0d41fe3c4585","published":"2015-01-25T20:59:53.836Z","updated":"2015-01-27T15:16:12.247Z"},"id":"urn:uuid0803e933-0011-464a-8ea2-5187b8ec4487","link":[{"href":"https://ord.feeds.api.rackspacecloud.com/feed_1/events/5821027","rel":"current"},{"href":"https://storage.stg.swift.racklabs.com/v1/StagingUS_cab08997-1c5d-4545-815a-186592907ef9/container_1/ord_feed_1-events_2015-01-27.json","rel":"self"},{"href":"https://storage.stg.swift.racklabs.com/v1/StagingUS_cab08997-1c5d-4545-815a-186592907ef9/container_1/ord_feed_1-events_2015-01-28.json","rel":"prev-archive"},{"href":"https://storage.stg.swift.racklabs.com/v1/StagingUS_cab08997-1c5d-4545-815a-186592907ef9/container_1/ord_feed_1-events_2015-01-26.json","rel":"next-archive"}],"title":{"@text":"feed_1/events","type":"text"},"updated":"2015-01-28T15:50:48.497Z"}}

Learn about the available Cloud Feeds API resources and methods, and review message
samples for each product event type.

You can use the Cloud Feeds API operations to access near real-time usage and system
events and information for Rackspace services that can be used for analysis,
monitoring, and automation.

The following table lists the available Cloud Feed product event feeds available along
with the API endpoints for accessing them. Use the
get feed catalog operation to retrieve the
most current list of feeds.

This event provides information about the creation of a user token revocation record
(TRR) in the Rackspace Identity service, version 1.

Attribute Name

Description

Type

Optionality

tenants

Specifies the
space separated
IDs of the
tenant
associated with
this user, if
any.

string*

Optional

tokenCreationDate

Specifies the
date to compare
against a
token's creation
date. Tokens
that were
created before
this date (and
match the other
criteria in the
TRR) should be
considered
revoked

utcDateTime

Required

Attribute Group: The tokenAuthenticatedBy attribute group specifies a
set of authentication method(s) to compare to a token's authenticationBy
attribute. If the tokenAuthenticatedBy element is included in the TRR,
the tokenAuthenticatedBy element is included in the TRR, then this
attribute is not used to limit which tokens are considered revoked.
The tokenAuthenticatedBy element can occur zero to 10 times, depending on
on whether the token has associated multi-factor authentication passcodes.
The group can contain one or more of the following authentication type

Enable or Disable Half-Closed
support for the load balancer.
Half-Closed support provides the
ability for one end of the
connection to terminate its
output, while still receiving
data from the other end. This
option is only available for TCP
and TCP_CLIENT_FIRST protocol
values.

boolean

Optional

networkItemId

Specifies the network item Id.

int

Required

accessAddress

Specifies the IP address.

string

Optional

accessType

Specifies the access type. Can
be either 'ALLOW' or 'DENY'.
Allowed Values: ALLOW,
DENY

string

Optional

minConnections

Specifies the minimum number of
connections.

integer

Optional

maxConnections

Specifies the maximum number of
connections.

integer

Optional

maxConnectionRate

Specifies the maximum connection
rate.

integer

Optional

rateInterval

Specifies the rate interval.

integer

Optional

persistenceType

Specifies the method for
persisting the session. Can be
either 'HTTP_COOKIE' or
'SOURCE_IP'. Allowed Values:
HTTP_COOKIE, SOURCE_IP