MOStlyREST com_rest_content


The MOStlyREST com_rest_content component builds off the solid MOStlyREST com_rest base component. It implements a set of standard REST parameters for interacting with Mambo's com_content. Exposing com_content in this fashion allows for programmatic access to content items, sections, categories, searching, etc. See the table below for information on allowed parameters and their meaning. See the SMRC and Bridget sample apps for a hands-on example of com_rest_content.




RESTful API Parameters, Explanations, and Formats

Parameter Value Description
appid string (required) The application ID. See the wiki page on RESTful API registration for more information.
output string: json, xml, php The format the API response is to be returned in. More information on the return formats can be found later in this document.
callback string The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9 . [] and _. If output=json has not been requested, this parameter has no effect.
query string A query can be passed as an additional filter to isolate matching content items to return. This query only effects requests of type "content". The query string must be rawurlencoded. A rawurldecode is done on the string as part of the normal internal API processing. The following fields are searched with the query string:
  • title
  • title_alias
  • introtext
  • fulltext
  • metakey
  • metadesc
type content, rank, popular, section The type of API request being made. Content, rank, and popular all three return 10 results by default and a maximum of 100 content items per request. Developers may use the "start" parameter as an offset to continue fetching and/or the "results" parameter to alter the number of results grabbed per request.
  • content - Request acts on all the content. To get just a single content item use type=content and contentid=some id here.
  • rank - Request returns content items in descending order (highest to lowest) based on their end-user rating score (i.e.) rating_sum / rating_count. Could be useful in grabbing things like the top 10 rated items.
  • popular - Request returns content items in descending order (highest to lowest) based on the number of views/hits they have received. Could be useful in grabbing things like the top 10 most read items.
contentid integer The contentid of a specific content item to return.
Note: Only honored in requests of type=content.
sectionid
integer
The sectionid of a specific section to return
Note: Only honored in requests of type=section and type=content.
categoryid integer
The categoryid of a specific category to return
Note: Only honored in requests of type=content.
show_categories
string: y, n (default)
Flag that enables the retrieval of categories. It is disabled by default. If enabled and type=section then along with the section being returned the response will also contain the categories that belong to each.
Note: Only honored in requests of type=section.
create_date_sort string: asc, desc (default)
Changes the sort order of content to be returned. It defaults to "desc" which means the newest content items are return first.
Note: Only honored in requests of type=content.
results integer: default 10, max 100 The number of results to return.
start integer: default 1 The starting result position to return (i.e.) the offset. The finishing position will calculated as (start + results - 1). Remember you cannot return more than 100 records at a time.



Each request must start with a base URL. Below is a sample base URL. To build custom API requests the parameters discussed above can be combined and tacked onto the site's base URL.

Sample base URL:

http://example.com/index2.php?option=com_rest_content&task=dataRetrival&no_html=1;

Sample custom request URL:
http://example.com/index2.php?option=com_rest_content&no_html=1&task=dataRetrival&appid=1ccbb11822d9acd695884fb034167a01&type=content&output=xml&contentid=23;


API Sample Content Responses


XML

<ResultSet>
    <Result>
        <id>23</id>
        <link><![CDATA[http://example.com/index.php?option=com_content&task=view&id=27]]></link>       
        <title><![CDATA[Can users edit content from the front end?]]></title>
        <title_alias><![CDATA[Can users edit content from the front end?]]></title_alias>
        <introtext><![CDATA[<p>Yes, if they are registered users...</p>]]></introtext>
        <fulltext/>
        <sectionid>3</sectionid>
        <section><![CDATA[Frequently Asked Questions]]></section>
        <catid>17</catid>
        <category><![CDATA[Managing Users]]></category>
        <mask>0</mask>
        <author>Administrator</author>
        <created>2021-11-22 02:49:48</created>
        <modified>2021-05-14 18:22:43</modified>
        <publish_up>2021-11-22 00:00:00</publish_up>
        <publish_down>0000-00-00 00:00:00</publish_down>
        <images/>
        <urls/>
        <attribs/>
        <version>6</version>
        <parentid>0</parentid>
        <ordering>1</ordering>
        <metakey/>
        <metadesc/>
        <hits>3</hits>
        <rating/>
        <rating_count/>
    </Result>
</ResultSet>


JSON


[{"id":"23",
"link":"http://example.com/index.php?option=com_content&task=view&id=27",
"title":"Can users edit content from the front end?",
"title_alias":"Can users edit content from the front end?",
"introtext":"<p>Yes, if they are registered users...",
"fulltext":"",
"sectionid":"3",
"section":"Frequently Asked Questions",
"catid":"17",
"category":"Managing Users",
"mask":"0",
"author":"Administrator",
"created":"2005-11-22 02:49:48",
"modified":"2007-05-14 18:22:43",
"publish_up":"2005-11-22 00:00:00",
"publish_down":"0000-00-00 00:00:00",
"images":"",
"urls":"",
"attribs":"",
"version":"6",
"parentid":"0",
"ordering":"1",
"metakey":"",
"metadesc":"",
"hits":"3",
"rating":null,
"rating_count":null
}]



PHP


a:1:{
	i:0;
	O:8:"stdClass":26:{
		s:2:"id";
		s:2:"23";
		s:5:"link";		
		s:XXX:"http://example.com/index.php?option=com_content&task=view&id=27";		
		s:5:"title";
		s:42:"Can users edit content from the front end?";
		s:11:"title_alias";
		s:42:"Can users edit content from the front end?";
		s:9:"introtext";
		s:536:"<p>Yes, if they are registered users...";
		s:8:"fulltext";
		s:0:"";
		s:9:"sectionid";
		s:1:"3";
		s:7:"section";
		s:26:"Frequently Asked Questions";
		s:5:"catid";
		s:2:"17";
		s:8:"category";
		s:14:"Managing Users";
		s:4:"mask";
		s:1:"0";
		s:6:"author";
		s:13:"Administrator";
		s:7:"created";
		s:19:"2005-11-22 02:49:48";
		s:8:"modified";
		s:19:"2007-05-14 18:22:43";
		s:10:"publish_up";
		s:19:"2005-11-22 00:00:00";
		s:12:"publish_down";
		s:19:"0000-00-00 00:00:00";
		s:6:"images";
		s:0:"";
		s:4:"urls";
		s:0:"";
		s:7:"attribs";
		s:182:"";
		s:7:"version";
		s:1:"6";
		s:8:"parentid";
		s:1:"0";
		s:8:"ordering";
		s:1:"1";
		s:7:"metakey";
		s:0:"";
		s:8:"metadesc";
		s:0:"";
		s:4:"hits";
		s:1:"3";
		s:6:"rating";
		N;
		s:12:"rating_count";
		N;
	}
}



API Sample Section/Category Responses


XML


<Sections>
    <Section>
        <id>4</id>
        <link><![CDATA[http://example.com/index.php?option=com_content&task=category§ionid=4]]></link>   
        <title><![CDATA[Getting Started]]></title>
        <name><![CDATA[Getting Started]]></name>
        <description></description>
        <scope>content</scope>
        <ordering>1</ordering>
        <Categories>
            <Category>
                <id>16</id>
                <link>http://example.com/index.php?option=com_content&task=category§ionid=4&id=16</link>
                <parent_id>0</parent_id>
                <title><![CDATA[Getting Started]]></title>
                <name><![CDATA[Getting Started]]></name>
                <description><![CDATA[<p><strong>Explanatory Note</strong> - This set of content ..... </p>]]></description>
                <ordering>1</ordering>
            </Category>
        </Categories>
    </Section>
</Sections>


JSON


[{
"id":"2",
"link":"http://example.com/index.php?option=com_content&task=category§ionid=2";
"title":"Newsflashes",
"name":"Newsflashes",
"description":"<p><strong>Explanatory Note<\/strong> -- This Section...<\/p>",
"scope":"content",
"ordering":"2",
"categories":[{
			"id":"3",
			"link":"http://example.com/index.php?option=com_content&task=category§ionid=2&id=3"
			"parent_id":"0",
			"title":"Newsflash",
			"name":"Newsflash",
			"description":"<p><strong>Explanatory Note<\/strong> - This Category...<\/p>",
			"ordering":"1"
			}]
}]


PHP


a:1:{
	i:0;
	a:7:{
		s:2:"id";
		s:1:"2";
		s:5:"link";		
		s:XXX:"http://example.com/index.php?option=com_content&task=category§ionid=2";				
		s:5:"title";
		s:11:"Newsflashes";
		s:4:"name";
		s:11:"Newsflashes";
		s:11:"description";
		s:354:"<p><strong>Explanatory Note</strong> -- this...</p>";
		s:5:"scope";
		s:7:"content";
		s:8:"ordering";
		s:1:"2";
		s:10:"categories";
		a:1:{
			i:0;
			a:6:{
				s:2:"id";
				s:1:"3";
				s:9:"parent_id";
				s:1:"0";
				s:5:"link";		
				s:XXX:"http://example.com/index.php?option=com_content&task=category§ionid=2&id=3";									
				s:5:"title";
				s:9:"Newsflash";
				s:4:"name";
				s:9:"Newsflash";
				s:11:"description";
				s:345:"<p><strong>Explanatory Note</strong> - This Category...</p>";
				s:8:"ordering";
				s:1:"1";
			}
		}
	}
}

Page was generated in 0.1224 seconds