Developer Resources

API Documentation

Help :: Developer Resources

Last modified: 2:57 pm on September 26, 2011           Article: 3-28

The Concerto 1.x API is accessible via http://concerto_installation_root/content/render/, where concerto_installation_root is the root address to your Concerto installation. For example, the RPI API URL would be http://concerto.rpi.edu/content/render/. Send any of the following parameters via GET or POST format to interact with the system. Feel free to mix and match to create your own Concerto looking glass! Underlined acceptable values indicate the default selections. The only required parameter is select_id (except for system queries).

Disclaimer: This API specification is subject to change quickly and without warning, though we try very hard not to break anything.

Download the PDF

A complete PDF of everything that's on this page may be downloaded here.

API Call Parameter Details

Parameter
* Required
Default Options
select feed content, feed, user, system
select_id* null integer, string
format rss raw, html, rawhtml, rss, json
orderby id id, rand, type_id, mime_type, submitted, start_time, end_time, user_id
range live live, future, past, all
count null integer
type null string
width null integer
height null integer
callback null string
api null integer



 

Parameter: select

Acceptable Values: content, feed, user, system

Select controls the grouping by which content returned from the system.

  • content: Selects one piece of content matching select_id. All other selection criterial are ignored.
  • feed: Select all the content on approved on the feed with the id select_id. Criteria are used to limit content returned.
  • user: Select all the content submitted to the system by the user with the username select_id that has been approved on at least one feed.
  • system: Special query used to access system data. This is the only case a select_id is not required. See examples.

 

Parameter: select_id

integer, string

REQUIRED. Specifies the value to satisfied for the type of selection needed.

  • integer: The id of a feed or piece of content to be selected based on the select parameter
  • string: The username of a user whoʼs content should be selected.

 

Parameter: format

raw, html, rawhtml, rss, json

Controls the output format of the result set.

  • raw: For text content, returns the text of each entry followed by a newline/ For image based content, this function will render the image, returning image data to the browser.
  • html: Output marked up html (wrapped in divs) with the content text or an image tag referencing the source of the image.
  • rawhtml: Output simple html with the content text or image tags. No divs are used to wrap the output.
  • rss: Output an rss feed containing information about all the content selected, includes media rss and dcterms.
  • json: Output JSON data containing information about all the content selected.

 

Parameter: orderby

id, rand, type_id, mime_type, submitted, start_time, end_time, user_id

If more than one item is being returned, control the ordering of the content items.

  • id: Sort content by the content item's unique id.
  • rand: Randomly order the content.
  • type_id: Sort content by the type of it in the system, such as graphics, ticker text, html dynamic text, etc.
  • mime_type: Sort content based on the mime type of the content item, such as image/jpeg, image/png, image/gif, text/plain, text/html.
  • submitted: Sort content by the date it was submitted to the system.
  • start_time: Sort content by the time it should start being displayed.
  • end_time: Sort content by the time it should stop being displayed.
  • user_id: Sort content by the user_id of the person who submitted it.

 

Parameter: range

live, future, past, all

Control the date range used when selecting content.

  • live: Content currently being shown on the system; start time < current time < end time
  • future: Content not currently being shown, but to be shown later: start time > current time
  • past: Content not currently being shown, but has been previously shown; end time < current time
  • all: Select content regardless of its start and end time.

 

Parameter: count

integer

Used to limit the content returned from the system to a specific amount.

  • integer: Return a maximum of integer pieces of content.

 

Parameter: type

string

Control the nature of content returned from the system, based on the areas it would be displayed on a screen.

  • string: Select only content that belongs in a field described by string. Types defined in the system can be identified with a select = system query.

 

Parameter: width

integer

If returning image content, limit the width to a maximum.

  • integer: If the content is an image, the max width of the content will be integer. Content will be scaled proportionally, but resulting width will not be larger than specified.

 

Parameter: height

integer

See parameter: width.

 

Parameter: callback

string

For json queries, the callback parameter will wrap the JSON output with a JSON-P style callback.

  • string: The name of the function the output should be wrapped in. Some libraries (like jQuery) would prefer to fill this parameter in automatically if located at the end of your query string.

 

Parameter: api

integer

Used to control the version of the API used to execute the query.

  • integer: The api matching integer will be used to execute the query if it exists. If not, the default API will be used. 000 will return the parameters you are passing in to the API for debugging/verification.


 

Usage Examples

View examples of using the API at the full PDF document, which you can view here.





Got a comment about this page?