Info
Official mRcore4 RESTful API Documentation!


Summary[-][--][++]

Info
Right Why?
I have created several RESTful API's simply because I wanted to learn how to develop webservices using PHP and REST. I sort of followed Twitters API URL style (http://dev.twitter.com/doc), if they can't do REST, no one can eh? Eventually I would like to create a native Android application for mRcore4 using these API's, and possibly experiment abstracting the database layer completely, making all queries through an API. It has already come in handy from a Linux command line. I created a bash script so I can simply type mr.topic 1 to get the plaintext version of topic ID 1, or mr.topic search linux to list all topics in plaintext that contain the word linux. Very handy since I'm in the command line 90% of the time. I can even append quick strings to an article with mr.topic append 1 'found a cool command line thingy here...'.

Right Authentication and Permissions
I use two types of authentication, Basic HTTP Authentication and Digest Authentication. Digest is the preferred method and if you are using a script as a webservice client (opposed to straight command line curl) I suggest you use the Digest parameters of curl. Basic HTTP Authentication is used if called from a command line (curl -u user:pass). The credentials and permissions used are the same as your regular website login account therefore you can only view and edit topics that you would normally have access too. Most of the API's can be accessed anonymously and do NOT require user authentication. To gain public access to an API you can either omit the user/pass or set the user/pass to anonymous.

Right Syntax
In the API documentation below, v stands for the API version number (versions are in the form of v1 v2 v3...), tid is a variable describing the topic ID, format is a variable describing the output format (options are xml or json). The output format can either be specified through the URL (rest/v/topic/255.json) or through the html Accept Header (curl -H "Accept: application/json"). The URL method is preferred and takes precedence over the Accept header and json is always the default output format if none is specified.

Construction
The API is currently under construction, there will be lots more API functions soon, not that anyone cares since I'm the only one using it Rolling Eyes

Topic API[-][--][++]

Get Topic[-][--][++]

  • Methods: GET, POST
  • Formats: json, xml
  • Anonymous Access: true
  • Optional Parameters:
    • plaintext=1 returns only the topic body as plain text (plain wiki syntax, not wiki parsed)
  • GET
    • URL: http://mreschke.com/rest/v/topic/tid.format?optionalparamsX=Y
    • CURL: curl -u user:pass http://mreschke.com/rest/v/topic/tid.format
  • POST
    • URL: http://mreschke.com/rest/v/topic/ (if passing format as Accept header)
    • URL: http://mreschke.com/rest/v/topic/.format (if passing format in URL)
    • CURL: curl -u user:pass -H "Accept: application/format" -X POST -d "topic_id=tid" http://mreschke.com/rest/v/topic (if passing format via Accept header)
    • CURL: curl -u user:pass -X POST -d "topic_id=tid&optionalparamX=Y" http://mreschke.com/rest/v/topic/.format (if passing format via URL, note .format is optional will default to json)

Search API[-][--][++]

Live Sample: http://mreschke.com/rest/v1/search/.xml
Live Sample: http://mreschke.com/rest/v1/search/.json
Live Sample: http://mreschke.com/rest/v1/search/.xml?plaintext=1
Live Sample: http://mreschke.com/rest/v1/search/*/LINUX.xml

Current Version is v1

This API uses the same URL scheme that my sites main /search page uses, so /search/*/LINUX for all LINUX badged articles, or /search/query+here to search for your query... So using POST really isn't that beneficial since the only thing to POST is the optional parameters.

Use URL encoding for spaces, example, /search/my+query+with+spaces
xxx means the standard URL based search parameters used by this websites search engine

Get Search Results[-][--][++]

  • Methods: GET, POST
  • Formats: json, xml
  • Anonymous Access: true
  • Optional Parameters:
    • plaintext=1 returns only the resulting title, creator and teaser in plain text format
  • GET
    • URL: http://mreschke.com/rest/v/search/xxx.format?optionalparamsX=Y
    • CURL: curl -u user:pass http://mreschke.com/rest/v/search/xxx.format?optionalparamsX=Y
  • POST
    • URL: http://mreschke.com/rest/v/search/xxx.format
    • CURL: curl -u user:pass -X POST -d "optionalparamxX=Y" http://mreschke.com/rest/v/search/xxx.format (notice even the method is POST I still get the actual search parameters from the URL, not POSTed data)**

PHP Client[-][--][++]

Easily create a PHP client like this

$jsonurl = 'http://mreschke.com/rest/v1/topic/255.json';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $jsonurl);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, 1);  
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT, 10);
$json = curl_exec($ch);
curl_close($ch);
echo $json;