Developer Reference

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

• Overview
• API Root
• News Item Collection
• News Item
• Category Collection
• Photo Collection
• Value Types

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

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.

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

Optional Elements

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.

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.

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

[Jump to top]