Update Forums documentation

Signed-off-by: Eric Poirier <eric.poirier@eclipse-foundation.org>

src/modules/forums.apib

@@ -3,12 +3,13 @@ Eclipse Forums are available through this resource.
 
 
 
-## Fetch Categories [GET /forums/category{?page,pagesize}]
+## Fetch Categories [GET /forums/category{?page,pagesize,order_by}]
 Retrieve a list of all the categories from the Eclipse Forums.
 
 + Parameters
     + page (integer, optional) - The index of the page to get, defaults to 1.
     + pagesize (integer, optional) - The number of records to get per page, defaults to 20. Maximum value is 100.
+    + order_by (string, optional) - The order by ID in which the results will be returned. DESC by default
 
 + Response 200 (application/json)
     + Headers
@@ -19,7 +20,7 @@ Retrieve a list of all the categories from the Eclipse Forums.
         Content-Type: application/json
         
     + Body
-        {"forums_category":[{"id":"1","name":"Eclipse Projects","url":"https://www.eclipse.org/forums/index.php/i/1","description":" - Eclipse Project Forums - click +/- to expand/collapse","forum_url":"https://api.eclipse.org/forums/forum?category_id=1"},{"id":"2","name":"Newcomers","url":"https://www.eclipse.org/forums/index.php/i/2","description":" - General Newcomer discussions","forum_url":"https://api.eclipse.org/forums/forum?category_id=2"}]}
+        {"pagination":{"page":1,"pagesize":2,"result_start":1,"result_end":2,"result_size":2,"total_result_size":9},"result":[{"id":"10","name":"ice","description":"","url":"https://www.eclipse.org/forums/index.php/i/10/","forums_url":"https://api.eclipse.org/forums/forum?category_id=10"},{"id":"8","name":"Archived","description":" - Forums for projects that have been officially archived.","url":"https://www.eclipse.org/forums/index.php/i/8/","forums_url":"https://api.eclipse.org/forums/forum?category_id=8"}]}
 
 
 
@@ -37,17 +38,20 @@ Retrieve a specific category from the  Eclipse Forum's.
         Content-Type: application/json
         
     + Body
-        {"id":"1","name":"Eclipse Projects","url":"https://www.eclipse.org/forums/index.php/i/1","description":" - Eclipse Project Forums - click +/- to expand/collapse","forum_url":"https://api.eclipse.org/forums/forum?category_id=1"}
+        {"id":"10","name":"ice","description":"","url":"https://www.eclipse.org/forums/index.php/i/10/","forums_url":"https://api.eclipse.org/forums/forum?category_id=10"}
 
 
 
-## Fetch Forums [GET /forums/forum{?category_id,page,pagesize}]
+## Fetch Forums [GET /forums/forum{?category_id,page,pagesize,order_by,since,until}]
 Retrieve a list of all the forums from the Eclipse Forums based on a category id if specified.
 
 + Parameters
     + category_id (integer, optional) - Unique identifier for a category
     + page (integer, optional) - The index of the page to get, defaults to 1.
     + pagesize (integer, optional) - The number of records to get per page, defaults to 20. Maximum value is 100.
+    + order_by (string, optional) - The order created date in which the results will be returned. DESC by default
+    + since (integer, optional) - The results since a timestamp onward
+    + until (integer, optional) - The results until a timestamp
 
 + Response 200 (application/json)
     + Headers
@@ -58,7 +62,7 @@ Retrieve a list of all the forums from the Eclipse Forums based on a category id
         Content-Type: application/json
         
     + Body
-        {"forums_forum":[{"id":"2","name":"BIRT","category_id":"1","url":"https://www.eclipse.org/forums/index.php/f/2","description":"Questions, technical discussions and resources on the Business Intelligence and Reporting Tools (BIRT) Project   <a class='smallLink' href='http://www.eclipse.org/birt/'>[project home]</a>","date_created":"1248706783","thread_count":"28740","post_count":"93781","last_post_id":"1780940","category_url":"https://api.eclipse.org/forums/category/1","topics_url":"https://api.eclipse.org/forums/topic?forum_id=2"}]}
+        {"pagination":{"page":1,"pagesize":1,"result_start":1,"result_end":1,"result_size":1,"total_result_size":391},"result":[{"id":"2","name":"BIRT","category_id":"1","url":"https://www.eclipse.org/forums/index.php/f/2","description":"Questions, technical discussions and resources on the Business Intelligence and Reporting Tools (BIRT) Project   <a class='smallLink' href='http://www.eclipse.org/birt/'>[project home]</a>","date_created":"1248706783","thread_count":"28740","post_count":"93781","last_post_id":"1780940","category_url":"https://api.eclipse.org/forums/category/1","topics_url":"https://api.eclipse.org/forums/topic?forum_id=2"}]}
 
 
 
@@ -80,13 +84,16 @@ Retrieve a specific forum from the Eclipse Forums.
 
 
 
-## Fetch Topics [GET /forums/topic{?forum_id,page,pagesize}]
+## Fetch Topics [GET /forums/topic{?forum_id,page,pagesize,order_by,since,until}]
 Retrieve a list of all the topics from the Eclipse Forums based on a forum id if specified.
 
 + Parameters
     + forum_id (integer, optional) - Unique identifier for a forum
     + page (integer, optional) - The index of the page to get, defaults to 1.
     + pagesize (integer, optional) - The number of records to get per page, defaults to 20. Maximum value is 100.
+    + order_by (string, optional) - The order created date in which the results will be returned. DESC by default
+    + since (integer, optional) - The results since a timestamp onward
+    + until (integer, optional) - The results until a timestamp
 
 + Response 200 (application/json)
     + Headers
@@ -97,7 +104,7 @@ Retrieve a list of all the topics from the Eclipse Forums based on a forum id if
         Content-Type: application/json
         
     + Body
-        {"forums_topic":[{"id":"2","forum_id":"2","last_post_date":"1489947260","root_msg_id":"2","replies":"1","views":"113121","url":"https://www.eclipse.org/forums/index.php/t/2","last_post_id":"1757399","forum_url":"https://api.eclipse.org/forums/forum/2","posts_url":"https://api.eclipse.org/forums/post?topic_id=2"}]}
+        {"pagination":{"page":1,"pagesize":1,"result_start":1,"result_end":1,"result_size":1,"total_result_size":892958},"result":[{"id":"2","forum_id":"2","last_post_date":"1489947260","root_msg_id":"2","replies":"1","views":"113121","url":"https://www.eclipse.org/forums/index.php/t/2","last_post_id":"1757399","forum_url":"https://api.eclipse.org/forums/forum/2","posts_url":"https://api.eclipse.org/forums/post?topic_id=2"}]}
 
 
 
@@ -119,13 +126,16 @@ Retrieve a specific topic from the Eclipse Forums.
 
 
 
-## Fetch Posts [GET /forums/post{?topic_id,page,pagesize}]
+## Fetch Posts [GET /forums/post{?topic_id,page,pagesize,order_by,since,until}]
 Retrieve a list of all the posts from the Eclipse Forums based on a topic_id if specified.
 
 + Parameters
     + topic_id (integer, optional) - Unique identifier for a topic
     + page (integer, optional) - The index of the page to get, defaults to 1.
     + pagesize (integer, optional) - The number of records to get per page, defaults to 20. Maximum value is 100.
+    + order_by (string, optional) - The order created date in which the results will be returned. DESC by default
+    + since (integer, optional) - The results since a timestamp onward
+    + until (integer, optional) - The results until a timestamp
 
 + Response 200 (application/json)
     + Headers
@@ -136,7 +146,7 @@ Retrieve a list of all the posts from the Eclipse Forums based on a topic_id if
         Content-Type: application/json
         
     + Body
-        {"forums_post":[{"id":"1779792","subject":"Subclipse problem","topic_id":"1091069","poster_id":"106173","created":"1515775710","url":"https://www.eclipse.org/forums/index.php?t=msg&th=1091069&goto=1779792&#msg_1779792","body":"Hi,<br /><br />I was wondering if there is a way to force to redraw the whole Eclipse window. If not, I think it would be beneficial to have one if it's possible to implement, because lately - especially since the GTK2 -> GTK3 transition started - Eclipse became more and more buggy in this area (at least the Linux version).<br /><br />I know that it would be only a workaround, and if there's a specific bug then it should be hunted down and corrected instead, but the bug hunting approach of solving the screen update issues works only on the long run. On one hand, many times the bug is in an underlying external component (such as GTK, some font rendering library, Linux video driver), and it's hard to make them correct the bug - that is, if they admit it's a bug and the discussion does not end up in a pointless flamewar instead. On the other hand, even if a bug is corrected, sometimes the correction is only available in the next release of Eclipse/Linux/GTK/whatever, so you end up waiting years to get it in a stable, packaged way, or you have to use experimental stuff which might even need compilation from scratch, etc.<br /><br />So, I'd like to ask if anyone knows whether it is technically possible to implement a "forced screen redraw" feature in Eclipse in a general way, so that the notorious screen garbage problems could be mitigated?","topic_url":"https://api.eclipse.org/forums/topic/1091069","topic_posts_url":"https://api.eclipse.org/forums/post?topic_id=1091069"}]}
+        {"pagination":{"page":1,"pagesize":1,"result_start":1,"result_end":1,"result_size":1,"total_result_size":1645105},"result":[{"id":"1779792","subject":"Subclipse problem","topic_id":"1091069","poster_id":"106173","created":"1515775710","url":"https://www.eclipse.org/forums/index.php?t=msg&th=1091069&goto=1779792&#msg_1779792","body":"Hi,<br /><br />I was wondering if there is a way to force to redraw the whole Eclipse window. If not, I think it would be beneficial to have one if it's possible to implement, because lately - especially since the GTK2 -> GTK3 transition started - Eclipse became more and more buggy in this area (at least the Linux version).<br /><br />I know that it would be only a workaround, and if there's a specific bug then it should be hunted down and corrected instead, but the bug hunting approach of solving the screen update issues works only on the long run. On one hand, many times the bug is in an underlying external component (such as GTK, some font rendering library, Linux video driver), and it's hard to make them correct the bug - that is, if they admit it's a bug and the discussion does not end up in a pointless flamewar instead. On the other hand, even if a bug is corrected, sometimes the correction is only available in the next release of Eclipse/Linux/GTK/whatever, so you end up waiting years to get it in a stable, packaged way, or you have to use experimental stuff which might even need compilation from scratch, etc.<br /><br />So, I'd like to ask if anyone knows whether it is technically possible to implement a "forced screen redraw" feature in Eclipse in a general way, so that the notorious screen garbage problems could be mitigated?","topic_url":"https://api.eclipse.org/forums/topic/1091069","topic_posts_url":"https://api.eclipse.org/forums/post?topic_id=1091069"}]}