{"topic_id":"255","post_id":"257","title":"mRcore4 API Documentation","teaser":"Official mRcore4 RESTful API Documentation! :r: 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 ha...","body":"<info>\r\n\r\n<box :info:>\r\nOfficial mRcore4 RESTful API Documentation!\r\n<\/box>\r\n\r\n[[toc]]\r\n<\/info>\r\n\r\n\r\n+Summary\r\n<box :info:>\r\n:r: **Why?**\r\nI 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...'}}.\r\n\r\n:r: **Authentication and Permissions**\r\nI 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.**\r\n\r\n:r: **Syntax**\r\nIn 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.\r\n<\/box>\r\n\r\n<box :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 :roll: <\/box>\r\n\r\n+Topic API\r\n\r\nLive Sample: http:\/\/mreschke.com\/rest\/v1\/topic\/255.xml\r\nLive Sample: http:\/\/mreschke.com\/rest\/v1\/topic\/255.json\r\nLive Sample: http:\/\/mreschke.com\/rest\/v1\/topic\/255?plaintext=1\r\n\r\n**Current Version is v1**\r\n\r\n++Get Topic\r\n* Methods: GET, POST\r\n* Formats: json, xml\r\n* Anonymous Access: true\r\n* Optional Parameters:\r\n * {{plaintext=1}} returns only the topic body as plain text (plain wiki syntax, not wiki parsed)\r\n* **GET**\r\n * URL: {{``http:\/\/mreschke.com\/rest\/v\/topic\/tid.format?optionalparamsX=Y``}}\r\n * CURL: {{``curl -u user:pass http:\/\/mreschke.com\/rest\/v\/topic\/tid.format``}}\r\n* **POST**\r\n * URL: {{``http:\/\/mreschke.com\/rest\/v\/topic\/``}} (if passing format as Accept header)\r\n * URL: {{``http:\/\/mreschke.com\/rest\/v\/topic\/.format``}} (if passing format in URL)\r\n * 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)\r\n * 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)\r\n\r\n\r\n\r\n+Search API\r\n\r\nLive Sample: http:\/\/mreschke.com\/rest\/v1\/search\/.xml\r\nLive Sample: http:\/\/mreschke.com\/rest\/v1\/search\/.xml?plaintext=1\r\nLive Sample: http:\/\/mreschke.com\/rest\/v1\/search\/*\/LINUX.xml\r\n\r\n**Current Version is v1**\r\n\r\nThis 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.\r\n\r\n**Use URL encoding for spaces, example, \/search\/my+query+with+spaces**\r\n**xxx means the standard URL based search parameters used by this websites search engine**\r\n\r\n++Get Search Results\r\n* Methods: GET, POST\r\n* Formats: json, xml\r\n* Anonymous Access: true\r\n* Optional Parameters:\r\n * {{plaintext=1}} returns only the resulting title, creator and teaser in plain text format\r\n* **GET**\r\n * URL: {{``http:\/\/mreschke.com\/rest\/v\/search\/xxx.format?optionalparamsX=Y``}}\r\n * CURL: {{curl -u user:pass ``http:\/\/mreschke.com\/rest\/v\/search\/xxx.format?optionalparamsX=Y``}}\r\n* **POST**\r\n * URL: {{``http:\/\/mreschke.com\/rest\/v\/search\/xxx.format``}}\r\n * 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)**\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n+PHP Client\r\nEasily create a PHP client like this\r\n<code type=\"php\">\r\n$jsonurl = 'http:\/\/mreschke.com\/rest\/v1\/topic\/255.json';\r\n$ch = curl_init();\r\ncurl_setopt($ch, CURLOPT_URL, $jsonurl);\r\ncurl_setopt($ch,CURLOPT_RETURNTRANSFER, 1);  \r\ncurl_setopt($ch,CURLOPT_CONNECTTIMEOUT, 10);\r\n$json = curl_exec($ch);\r\ncurl_close($ch);\r\necho $json;\r\n<\/code>\r\n","comments":[],"badges":[{"badge_id":"3","badge":"DEVELOPMENT","image":"badge3.png","default_topic_id":null,"topic_count":"40","selected":null},{"badge_id":"5","badge":"NETWORQMEDIA","image":"badge5.png","default_topic_id":null,"topic_count":"11","selected":null}],"tags":[{"tag_id":"58","tag":"custom","topic_count":"19","selected":null},{"tag_id":"82","tag":"json","topic_count":"1","selected":null},{"tag_id":"9","tag":"mrcore","topic_count":"3","selected":null},{"tag_id":"87","tag":"rest","topic_count":"1","selected":null},{"tag_id":"25","tag":"server","topic_count":"16","selected":null},{"tag_id":"88","tag":"webservice","topic_count":"3","selected":null},{"tag_id":"89","tag":"xml","topic_count":"1","selected":null}],"view_count":1492,"comment_count":"0","deleted":"0","created_by":"2","created_byTbl_user":{"user_id":"2","first_name":"Matthew","last_name":"Reschke","title":"Site Developer","alias":"mreschke","signature":"~\/Admin","description":"Administrator","avatar":"avatar_user2.png","created_by":"2","created_on":"2010-09-26 14:59:16","updated_on":"2011-11-10 13:17:56","last_login_on":"2012-05-18 09:43:31","disabled":"0","perm_create":"1","perm_admin":"1","topic_count":"288","comment_count":"1"},"created_on":"2011-06-14 12:37:23","updated_by":"2","updated_byTbl_user":{"user_id":"2","first_name":"Matthew","last_name":"Reschke","title":"Site Developer","alias":"mreschke","signature":"~\/Admin","description":"Administrator","avatar":"avatar_user2.png","created_by":"2","created_on":"2010-09-26 14:59:16","updated_on":"2011-11-10 13:17:56","last_login_on":"2012-05-18 09:43:31","disabled":"0","perm_create":"1","perm_admin":"1","topic_count":"288","comment_count":"1"},"updated_on":"2011-12-21 00:22:56"}