HomeSupportDeveloper Reference

This document covers feed structure. Looking for feed parsers? We have sample libraries in PHP, Visual Basic and C#, and Java.

Overview

This reference aims to cover the structure and content of an article feed. Working knowledge of XML and HTTP is assumed.

All requests to the API are made using HTTP GETs. Valid requests will be met with a HTTP 200 response code while invalid requests will be met with HTTP 4xx or 5xx codes.

This guide provides example URLs that correspond to the distributed parts of the content feed. With the exception of the API Root, it is strongly recommended to use provided href attributes to discover the URLs of feed content.

Key Terms

Feed
The set of XML documents that collectively provide Brafton content in a structured manner. The “feed” is not a reference to any specific XML structure, but rather the system as a whole.
Article
The eventual destination of the content as a coherent whole. As Brafton feeds are intended to be consumed by a variety of different content management systems and blogging software, this is an abstract concept. Precise definitions and implementation are left to the software in question.
API Domain
A feed’s serving domain, usually api.brafton.com. Provided by your account manager. Within this document, this is referenced by {API Domain} – you should replace this with your provided domain when querying the API.
API Key
A GUID that uniquely identifies a feed, provided by your account manager. Within this document, this is referenced by {API Key} – you should replace this with your provided key when querying the API.

[Jump to top]

API Root

The API Root is the starting point for feeds and their parsers, and provides core information such as the feed’s key, state, and URL where a collection of recently published content can be found (News Item Collection).

The URL for the API Root is http://{API Domain}/{API Key}/

Element Value Type Description
api XML Node The root node.
key GUID The feed’s identifying API Key.
name String The friendly name of the feed.
feedState Enumeration

The current status of the feed. This will be one of the following values:

  • Live – This feed can receive new content.
  • Trial – This feed is ready for testing purposes. Feeds in Trial house one or more example News Items.
  • Disabled – This feed does not receive new content.
news XML Node Provides the href attribute. The news element itself will have no inner text.
news [href] URL Specifies the URL of the collection of the most recently published content.
categoryDefinitions XML Node Provides the href attribute. The categoryDefinitions element itself will have no inner text.
categoryDefinitions [href] URL Specifies the URL of categories for content to be filed under. The data at the URL provided will be in the form of a Category Collection.

Example Response

<?xml version="1.0" encoding="utf-8"?>
<api xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <key>01234567-89ab-cdef-0123-456789abcdef</key>
    <name>Example Company</name>
    <feedState>Live</feedState>
    <news href="http://api.brafton.com/01234567-89ab-cdef-0123-456789abcdef/news/" />
    <categoryDefinitions href="http://api.brafton.com/01234567-89ab-cdef-0123-456789abcdef/categorydefinitions/" />
</api>

[Jump to top]

News Item Collection

The News Item Collection is the list of zero or more published news items within the last 30 days. If there has been no published items within 30 days, the collection will contain zero items.

The News Item Collection provides an overview of all News Items currently in the feed. The full content for a News Item can be retrieved at the URL provided within the newsListItem href attribute.

Element Value Type Description
news XML Node The root node for News Item Collections. Provides the state attribute, a mirror of the API Root’s feedState node.
newsListItem XML Node Represents a News Item in the collection. There may be zero or more newsListItem nodes within a News Item Collection. Each provides an href attribute.
newsListItem [href] URL Specifies the unique URL for the News Item, where the full text and metadata can be found.
id Integer Internal, unique ID for a News Item. These numbers are defined by Brafton and may not be sequential within a feed.
publishDate DateTime The date and time of the News Item’s approval by a client.
lastModifiedDate DateTime The date and time of the News Item’s last modification by a Brafton writer or editor.
headline String The title of the News Item.

Example Response

<?xml version="1.0" encoding="utf-8"?>
<news state="Live" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <newsListItem href="http://api.brafton.com/01234567-89ab-cdef-0123-456789abcdef/news/123456/">
        <id>123456</id>
        <publishDate>2009-12-04T13:00:00</publishDate>
        <lastModifiedDate>2009-12-06T15:50:31</lastModifiedDate>
        <headline>Example Article</headline>
    </newsListItem>
</news>

[Jump to top]

News Item

A News Item contains the content and metadata for an article. Libraries built against the feed should check for the existence of optional elements.

Required Elements

Element Value Type Description
newsItem XML Node The root node for a News Item. Provides the encoding attribute.
newsItem [encoding] Enumeration Defines the encoding for the feed’s content. May be one of the following values:

  • UTF-8 – The default feed encoding. Indicates the full Unicode character set may be used in content.
  • ASCII – Legacy option. Indicates only the ASCII character set may be used in content.
id Integer Internal, unique ID for a News Item. These numbers are defined by Brafton and may not be sequential within a feed.
state String Published state of the News Item. Deprecated. Will always be “Live”.
publishDate DateTime The date and time of the News Item’s approval by a client. Mirrors the respective publishDate within a News Item Collection.
createdDate DateTime The date and time of the News Item’s creation (when it was started by a Brafton writer).
lastModifiedDate DateTime The date and time of the News Item’s last modification by a Brafton writer or editor. Mirrors the respective lastModifiedDate within a News Item Collection.
headline String The title of the News Item.
categories XML Node Provides the href attribute. This node itself will contain no inner text.
Note: This node will be present even if the News Item has no associated Categories.
categories [href] URL Specifies the URL to the list of Categories this News Item is associated with. The data at the URL provided will be in the form of a Category Collection
photos XML Node Provides the href attribute. This node itself will contain no inner text.
photos [href] URL Specifies the URL to the list of Photos this News Item is associated with.
Note: This node will be present even if the News Item has no associated Photos.
text String The main content of a News Item. The inner text is HTML-formatted and may contain HTML tags and entities.

Optional Elements

Element Value Type Description
htmlTitle String Text intended to be used as or within the HTML title tag for the article.
htmlMetaDescription String Text intended to be used as or within the HTML meta description for the article.
extract String Introductory text for the News Item.
byline String The name of the author the article is to be attributed to.
source String Citation sources for the article, such as a website URL, newspaper, or other publication.
htmlMetaKeywords String List of comma-separated keywords to be used in the HTML meta keywords tag.
tags String List of comma-separated tags relating to the article.

Example Response

<?xml version="1.0" encoding="utf-8"?>
<newsItem encoding="UTF-8" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <id>123456</id>
    <state>Live</state>
    <publishDate>2009-12-04T13:00:00</publishDate>
    <createdDate>2009-12-02T09:41:05</createdDate>
    <lastModifiedDate>2009-12-06T15:50:31</lastModifiedDate>
    <headline>Example Article</headline>
    <extract>This text might appear as introductory text for your articles.</extract>
    <categories href="http://api.brafton.com/01234567-89ab-cdef-0123-456789abcdef/news/123456/categories/"/>
    <photos href="http://api.brafton.com/01234567-89ab-cdef-0123-456789abcdef/news/123456/photos/"/>
    <headline>Example Article</headline>
    <htmlMetaDescription>This text would go in the meta description of the page - this is what readers will see from search engines.</htmlMetaDescription>
    <text format="html"><p>The article body appears in the text tag.</p><p>Content from this tag will adapt to defined styles on your blog or content management system when published.</p></text>
</newsItem>

[Jump to top]

Category Collection

The Category Collection provides a list of categories. Items in this collection will refer to a set of shared categories for the feed. The collection itself may be associated with at most one News Item.

Element Value Type Description
XML Node Root node of a Category Collection containing zero or more child nodes. The name of this node differs depending on the current URL:

  • categoryDefinitions – if accessed via the API Root’s categoryDefinitions href
  • categories – if accessed via a News Item’s categories href
category XML Node Defines a single category.
id Integer Internal, unique ID for a Category. These numbers are defined by Brafton and may not be sequential within a feed.
name String The category’s human-readable name.

Example Response

<?xml version="1.0" encoding="utf-8"?>
<categories xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <category>
        <id>654321</id>
        <name>Example Category</name>
    </category>
</categories>

[Jump to top]

Photo Collection

A Photo Collection is a list of images associated with a News Item. Each item in a Photo Collection, a Photo, represents an image with a summary of its content. Each Photo will contain a set of child nodes that describe the photo’s physical attributes. This set is collectively called a Photo Instance.

Photos must be saved locally. Provided URLs are not for long-term serving and rendered inaccessible after 30 days.

Element Value Type Description
photos XML Node Root node of the collection. Contains zero or more child nodes.
photo XML Node Represents a Photo in the Collection. Contains child nodes for image metadata.
id Integer Internal, unique ID for a Photo. These numbers are defined by Brafton and may not be sequential within a feed.
caption String Text associated with the image, intended as a caption. Note: This node is optional and may not be present in all feeds.
htmlAlt String Text associated with the photo, intended as the image’s alt text. Note: This node is optional and may not be present in all feeds.
orientation Enumeration Defines the Photo’s major, or longest, axis. May be one of the following values:

  • Portrait – The major axis is the Y axis (longer height).
  • Landscape – The major axis is the X axis (longer width).
instances XML Node Parent node for Photo Instances. Contains one or more child nodes.
instance XML Node Defines a Photo Instance. Contains child nodes with additional image metadata.
width Integer The width of the Photo Instance, in pixels.
height Integer The height of the Photo Instance, in pixels.
type Enumeration The relative size of the Photo Instance. May be one of the following values:

  • Small – A relatively small-sized Instance of the Photo. Useful for thumbnails and low-resolution mobile devices.
  • Medium – A relatively medium-size Instance of the Photo. Useful for display alongside the full text of an article.
  • Large – A relatively large-size Instance of the Photo. Useful for displaying on its own to highlight detail or text that would otherwise be difficult to read.
  • Thumbnail – A thumbnail-sized Instance of the Photo. Useful for previews.

    Deprecated. Superceded by Small.

  • Fullsize – The original size of the photo. Useful for displaying detail or for display as a standalone image.

    Deprecated. Superceded by Large.

url URL The URL where this Photo Instance is temporarily served.

Note: Photo Instances invalidate after 30 days, and must be saved locally to ensure long-term storage. Do not link to a Photo Instance within an article.

Example Response

<?xml version="1.0" encoding="utf-8"?>
<photos xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <photo>
        <id>98765</id>
        <caption>A caption relating the article to the image.</caption>
        <htmlAlt>Text to provide in an alt tag, for accessibility.</htmlAlt>
        <orientation>Landscape</orientation>

        <instances>
            <instance>
                <width>500</width>
                <height>334</height>
                <type>Large</type>
                <url>http://pictures.brafton.com/Example-article-image.jpg</url>
            </instance>
        </instances>
    </photo>
</photos>

[Jump to top]

Value Types

Type Description Literals
DateTime A composition of a date component and a time component. A timestamp in ISO 8601 format.
GUID A Globally Unique IDentifier in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Case insensitive. Numbers 0-9 and letters a-f.
String A sequence of Unicode characters. Unless otherwise specified, Strings are free text and not sanitized for HTML or URL use. All Unicode characters. Escape sequences are not supported.
URL A sequence of Unicode characters that identifies an Internet resource. Valid URLs, beginning with http:// or https://.
Integer An unsigned 32-bit integer. All literals comprised of digits 0-9.
Enumeration A String that is constrained to a set of values. Please see the specific element’s description for a list of valid values. All Unicode characters. Escape sequences are not supported.

[Jump to top]