MOStlyREST com_rest RESTful API


The com_rest component implements a base REST component for other components to build on top of. These could be native core components and/or 3rd party custom components. This base component handles common tasks such as user API registration, API key regeneration, API key request validation, enabling/disabling of the REST interface, data encoding, setting of proper HTML header status codes and content types, error handling, logging of API requests, plus more. To summarize the base com_rest component extends the Mambo core and preps it for REST based interaction. This all done through standard conventions and no core hacks are required. At this point this REST implementation only allows for read access, but one could extend for write access as well if they were to implement security measures like OAuth for example.

Two items that should remain constant across all components within the REST family are the version check and error handling responses. Below you will find information on both.

Error Messages


When an error is encountered the API will response with the appropriate HTTP header.

Below are the headers currently in use:

  • HTTP/1.1 400 Bad Request
  • HTTP/1.1 401 Unauthorized

In addition to the HTTP headers being sent back the API will also respond with an error message body in the requested output format. JSON is the default response body when the "output" parameter was not defined in the request. Samples of the error body messages are shown below.

XML


<Error>
    <Message>Invalid appid used in request!</Message>
</Error>


JSON


{"Error":{"Message":"Invalid appid used in request!"}}


PHP


a:1:{
	s:5:"Error";
	a:1:{
		s:7:"Message";
		s:30:"Invalid appid used in request!";
	}
 }


Note: It's worth noting that errors are not the same as an empty result. An empty set will send back HTTP/1.1 200 OK with an empty response body.

Versioning


Like all software it is likely new versions, features, functionality, etc will be introduced into the MOStlyREST API over time. So in order to simplify discover of the version installed on a site and ease development against multiple versions developers can send a request of task=versioncheck. A response will be sent back in the requested return format, examples below:

Sample Version Check URL:
http://example.com/index2.php?option=com_rest&no_html=1&task=versioncheck&appid=1ccbb11822d9acd695884fb034167a01&output=xml;


Note: Valid output formats are json, xml, and php. A valid appid is also require for this request.

XML


<API>
    <Version>1.0</Version>
</API>


JSON


{"API":{"Version":"1.0"}}


PHP


a:1:{
	s:3:"API";
	a:1:{
		s:7:"Version";
		s:3:"1.0";
	}
}

Page was generated in 0.0780 seconds