Content API

kench edited this page Oct 13, 2014 · 9 revisions

Summary

Note: The Content API has not yet been implemented yet.

The Concerto Content API for Concerto 2.x provides a framework for facilitating programatic read-only access to the following public Concerto entities:

  • Feeds
  • Submissions
  • Content
  • Media

From the 7/1 Concerto developers Google+ Hangout, two implementations have been discussed:

  • Extend preexisting controllers to vend JSON feeds for the above entities.
  • Provide a separate route/API implementation using a new controller implementation to vend JSON feeds for the above entities.

The first approach reduces code duplication since most of the business logic surrounding these entities lives in the controllers at the expense of not providing a cohesive, versioned, and consistent API which is typically best practice.

The second approach provides a cohesive, versioned, and consistent API for developers to build applications utilizing Concerto content at the expense of duplicating business logic found in the controller code.

The Concerto v1 API documentation is available here for reference: http://www.concerto-signage.org/help_pages/28

Use Cases

  • Websites that wish to display content from a Concerto installation. The Rensselaer Union homepage is the most obvious example at the RPI deployment.
  • Concerto and 2nd-party applications (applications made by Rensselaer community members) for mobile devices and set top boxes that allow users to explore, browse, and discover Concerto content. Examples include iRPI, RPI Mobile, (speculative) Concerto for Android/iOS apps for viewing content, Concerto TV (APK for Google TV, Fire TV, and other Android STBs).
  • Facebook application (speculative) - allows RPI students to discover and share Concerto content on Facebook.

API Endpoints

Extend Existing Controllers

Feeds

List feeds

GET http://nightly.concerto-signage.org/feeds.json
Request
GET Parameters
Field Possible Values
filter submittable, viewable, public (submittable and viewable), restricted (not submittable and not viewable)
Response
[
    {
        content_types: [
            "Ticker",
            "Graphic",
            "SimpleRss",
            "RemoteVideo",
            "Weather",
            "Iframe",
            "Calendar"
        ],
        submissions: {
            active: 8,
            denied: 64,
            expired: 24,
            future: 12
        },
        description: "Rensselaer Union Clubhouse Pub",
        group_id: 1,
        id: 8,
        submittable: true,
        viewable: true,
        name: "Pub",
        parent_id: null,
        created_at: "2014-02-07T09:40:17-05:00",
        updated_at: "2014-02-07T09:40:17-05:00"
    },
    {
        content_types: [
            "Ticker",
            "SocialPost"
        ],
        submissions: {
            active: 8,
            expired: 24,
        },
        description: "#RPI2018 Infinity Social Media Posts",
        group_id: 2,
        id: 3,
        submittable: false,
        viewable: true,
        name: "#RPI2018",
        parent_id: null,
        created_at: "2014-02-07T09:40:17-05:00",
        updated_at: "2014-02-07T09:40:17-05:00"
    }
]

Show content/submissions for a feed

GET http://nightly.concerto-signage.org/feeds/1.json
GET http://nightly.concerto-signage.org/feeds/1.json?state=expired
GET http://nightly.concerto-signage.org/feeds/1.json?state=active&content_type=Graphic

Differs from human-friendly URL: http://nightly.concerto-signage.org/feeds/1/submissions?state=expired

Request
GET Parameters
Field Possible Values
state active, denied, expired, future
content_type Comma-separated list of content types to show
Response
{
    content_types: [
        "Ticker",
        "Graphic",
        "SimpleRss",
        "RemoteVideo",
        "Weather",
        "Iframe",
        "Calendar"
    ],
    submissions: [
        {
            children_count: 0,
            created_at: "2012-09-01T19:34:39-04:00",
            data: "This is another ticker test. The Web Technologies Group is awesome.",
            duration: 8,
            end_time: "2012-09-08T18:59:00-04:00",
            id: 12,
            kind: "Ticker",
            name: "WTG Test",
            parent_id: null,
            start_time: "2012-09-01T19:00:00-04:00",
            updated_at: "2012-09-01T19:34:39-04:00",
            user_id: 1,
            submission_id: 45,
            moderator_id: 2,
            approved: true,
            duration: 5,
            moderation_reason: "LGTM."
        },
        {
            media: {
                location: "http://nightly.concerto-signage.org/content/7064/display",
                content_type: "image/jpeg",
                file_name: "spectrum_of_the_sky_hdtv_1080p-HD.jpg",
                file_size: 10000,
            },
            children_count: 0,
            created_at: "2013-05-21T23:16:47-04:00",
            data: null,
            duration: 8,
            end_time: "2013-05-29T19:59:00-04:00",
            id: 7072,
            kind: "Graphic",
            name: "Spectrum of the Sky",
            parent_id: null,
            start_time: "2013-05-21T20:00:00-04:00",
            updated_at: "2013-05-21T23:16:47-04:00",
            user_id: 1,
            submission_id: 46,
            moderator_id: 2,
            approved: true,
            duration: 5,
            moderation_reason: "I CAN HAZ COLOURS!"
        }
    ],
    description: "Rensselaer Union Clubhouse Pub",
    group_id: 1,
    id: 8,
    submittable: true,
    viewable: true,
    name: "Pub",
    parent_id: null,
    created_at: "2014-02-07T09:40:17-05:00",
    updated_at: "2014-02-07T09:40:17-05:00"
}

Show submission status for a specified submission (feed/content pair)

GET http://nightly.concerto-signage.org/feeds/1/submissions/12.json
Request
GET Parameters
Field Possible Values
Response
{
    media: {
        location: "http://nightly.concerto-signage.org/content/7064/display",
        content_type: "image/jpeg",
        file_name: "spectrum_of_the_sky_hdtv_1080p-HD.jpg",
        file_size: 10000,
    },
    children_count: 0,
    created_at: "2013-05-21T23:16:47-04:00",
    data: null,
    duration: 8,
    end_time: "2013-05-29T19:59:00-04:00",
    id: 7072,
    kind: "Graphic",
    name: "Spectrum of the Sky",
    parent_id: null,
    start_time: "2013-05-21T20:00:00-04:00",
    updated_at: "2013-05-21T23:16:47-04:00",
    user_id: 1,
    user: {
        first_name: "Brian",
        last_name: "Zaik"
    },
    submission_id: 46,
    moderator_id: 2,
    approved: true,
    duration: 5,
    moderation_reason: "I CAN HAZ COLOURS!"
}

Show media for a piece of content

GET http://nightly.concerto-signage.org/content/7064.json

Note difference from human-centric URL: http://nightly.concerto-signage.org/feeds/1/submissions/1203