Recent changes to REST Interface

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Fri, 03 Feb 2012 01:03:08 -0000

--- v30 
+++ v31 
@@ -29,7 +29,7 @@
 * The second component is the HTTP method that is used when calling the function (get, put, post or delete).
 * The third component is the type of data that is consumed and produced (technically the GET and DELETE methods will consume any data type, since they don't take any data in the body of the request).
 * For GET and DELETE methods, the fourth component will be an entity id or ids, or the text "all". When specifying multiple ids, the format of the query parameter is "ids;1;3;235" e.g. http://localhost:8080/TopicIndex/seam/resource/rest/1/tags/delete/json?ids;1;3;235
-* For all jsonp methods, there is a query parameter called **callback** that defines the name of the function that will be called with the results. Using jQuery these jsonp functions can be called like **$.getJSON("http://localhost:8080/TopicIndex/seam/resource/rest/1/topic/get/jsonp/33?callback=?", function(json) {/* do something here */});**
+* For all jsonp methods, there is a query parameter called **callback** that defines the name of the function that will be called with the results. Using jQuery these jsonp functions can be called like **$.getJSON("http://localhost:8080/TopicIndex/seam/resource/rest/1/topic/get/jsonp/33?callback=?", function(json) {/\* do something here \*/});**
 
 The PUT and POST methods take a representation of the entities to be edited or created in the body of the request.

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Fri, 03 Feb 2012 01:02:24 -0000

--- v29 
+++ v30 
@@ -4,7 +4,7 @@
 
 The json methods return plain JSON objects, while the jsonp methods will return JSON objects wrapped in a function call to allow cross domain access to Javascript applications.
 
-As an example, the 8 functions for the tag entity are shown below:
+As an example, the 16 functions for the tag entity are shown below:
 
 * /tag/get/json/{id}
 * /tag/get/jsonp/{id}

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Fri, 03 Feb 2012 00:55:30 -0000

--- v28 
+++ v29 
@@ -1,22 +1,35 @@
 #OVERVIEW#
 
-The REST interface follows a few simple conventions. All primary entities (i.e. stand alone entities those whose lifecycle doesn't depend on another entity) have 8 standard methods. GET methods retrieve the entities, PUT methods update entities, POST methods create entities and DELETE methods delete entities. As an example, the 8 functions for the tag entity are shown below:
-
+The REST interface follows a few simple conventions. All primary entities (i.e. stand alone entities those whose lifecycle doesn't depend on another entity) have 16 standard methods. GET methods retrieve the entities, PUT methods update entities, POST methods create entities and DELETE methods delete entities.
+
+The json methods return plain JSON objects, while the jsonp methods will return JSON objects wrapped in a function call to allow cross domain access to Javascript applications.
+
+As an example, the 8 functions for the tag entity are shown below:
+
 * /tag/get/json/{id}
+* /tag/get/jsonp/{id}
 * /tags/get/json/all
+* /tags/get/jsonp/all
 * /tag/put/json
+* /tag/put/jsonp
 * /tags/put/json
+* /tags/put/jsonp
 * /tag/post/json
+* /tag/post/jsonp
 * /tags/post/json
+* /tags/post/jsonp
 * /tag/delete/json/{id}
+* /tag/delete/jsonp/{id}
 * /tags/delete/json/{ids}
+* /tags/delete/jsonp/{ids}
 
 The URLs are constructed with a number of standard components:
 
 * The first component of the url is the entity type (tag, topic, blobconstant etc). When the method acts on or returns multiple entities, the first component is a plural (tags, topics, blobconstants etc).
 * The second component is the HTTP method that is used when calling the function (get, put, post or delete).
 * The third component is the type of data that is consumed and produced (technically the GET and DELETE methods will consume any data type, since they don't take any data in the body of the request).
 * For GET and DELETE methods, the fourth component will be an entity id or ids, or the text "all". When specifying multiple ids, the format of the query parameter is "ids;1;3;235" e.g. http://localhost:8080/TopicIndex/seam/resource/rest/1/tags/delete/json?ids;1;3;235
+* For all jsonp methods, there is a query parameter called **callback** that defines the name of the function that will be called with the results. Using jQuery these jsonp functions can be called like **$.getJSON("http://localhost:8080/TopicIndex/seam/resource/rest/1/topic/get/jsonp/33?callback=?", function(json) {/* do something here */});**
 
 The PUT and POST methods take a representation of the entities to be edited or created in the body of the request.

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Wed, 25 Jan 2012 01:52:20 -0000

--- v27 
+++ v28 
@@ -345,13 +345,17 @@
 
 ~~~~~~~~
 {
-     "trunk":{
-        "name":"tags"
-     }
+   "branches":[
+      {
+         "trunk":{
+            "name":"tags"
+         }
+      }
+   ]
 }
 ~~~~~~~~
 
-An example of a call to http://localhost:8080/TopicIndex/seam/resource/rest/1/tags/get/json/all?expand=%7B%22trunk%22%3A%7B%22name%22%3A%22tags%22%7D%7D is:
+An example of a call to http://localhost:8080/TopicIndex/seam/resource/rest/1/tags/get/json/all?expand=%7B%22branches%22%3A%5B%7B%22trunk%22%3A%7B%22name%22%3A%22tags%22%7D%7D%5D%7D is:
 
 ~~~~~
 {

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Tue, 24 Jan 2012 23:40:41 -0000

--- v26 
+++ v27 
@@ -547,6 +547,8 @@
 
 Using the RESTEasy client, you can access the REST interface through the RESTInterfaceV1 interface.
 
+Note that when setting the properties on an entity to be created or updated, you can use the **setPropertyExplicit** methods. These will automatically populate the **configuredParameters** array with the correct values.
+
 ~~~~~~
 import java.net.URLEncoder;
 import java.util.ArrayList;

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Tue, 24 Jan 2012 23:05:48 -0000

--- v25 
+++ v26 
@@ -42,7 +42,7 @@
 
 ##ACCESSING PREVIOUS VERSIONS##
 
-All the entities have a collection called **revisions**. This is read only collection that contains the previous versions of an entity. It can be expanded like any other collection, but this collection will not be modified by any PUT or POST operations.
+All the entities have a collection called **revisions**. This is read only collection that contains the previous versions of an entity. It can be expanded like any other collection, but this collection will not be directly modified by any PUT or POST operations.
 
 ##CREATING AND UPDATING ENTITIES##

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Tue, 24 Jan 2012 23:04:48 -0000

--- v24 
+++ v25 
@@ -40,6 +40,10 @@
 
 The format for the queries used by the first two methods are the query parameters used by the Skynet web interface search results screen (e.g. **tag19=1&tag119=1&catint5=And&tag133=1&tag14=0&tag132=1**) prefixed with **query;**, and with all ampersand symbols replaced by semi colons. So the final results looks like **query;tag19=1;tag119=1;catint5=And;tag133=1;tag14=0;tag132=1**.
 
+##ACCESSING PREVIOUS VERSIONS##
+
+All the entities have a collection called **revisions**. This is read only collection that contains the previous versions of an entity. It can be expanded like any other collection, but this collection will not be modified by any PUT or POST operations.
+
 ##CREATING AND UPDATING ENTITIES##
 
 When updating an entity through a PUT method, or creating an entity through a POST method, it is possible to also create and remove relationships.

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Tue, 24 Jan 2012 03:50:42 -0000

--- v23 
+++ v24 
@@ -38,7 +38,7 @@
 * /topic/get/xml/{id}/xmlContainedIn - Returns the XML content of a topic enclosed in a new XML element supplied by the **container** query parameter
 * /topic/get/xml/{id}/xmlNoContainer - Returns the XML content of a topic without the root section element, and without the title element if the **includeTitle** query parameter is set to false
 
-The format for the queries used by the first two methods are the query parameters used by the Skynet web interface search results screen (e.g. *tag19=1&tag119=1&catint5=And&tag133=1&tag14=0&tag132=1*) prefixed with *query;*, and with all ampersand symbols replaced by semi colons. So the final results looks like *query;tag19=1;tag119=1;catint5=And;tag133=1;tag14=0;tag132=1*.
+The format for the queries used by the first two methods are the query parameters used by the Skynet web interface search results screen (e.g. **tag19=1&tag119=1&catint5=And&tag133=1&tag14=0&tag132=1**) prefixed with **query;**, and with all ampersand symbols replaced by semi colons. So the final results looks like **query;tag19=1;tag119=1;catint5=And;tag133=1;tag14=0;tag132=1**.
 
 ##CREATING AND UPDATING ENTITIES##

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Tue, 24 Jan 2012 03:45:31 -0000

--- v22 
+++ v23 
@@ -38,6 +38,8 @@
 * /topic/get/xml/{id}/xmlContainedIn - Returns the XML content of a topic enclosed in a new XML element supplied by the **container** query parameter
 * /topic/get/xml/{id}/xmlNoContainer - Returns the XML content of a topic without the root section element, and without the title element if the **includeTitle** query parameter is set to false
 
+The format for the queries used by the first two methods are the query parameters used by the Skynet web interface search results screen (e.g. *tag19=1&tag119=1&catint5=And&tag133=1&tag14=0&tag132=1*) prefixed with *query;*, and with all ampersand symbols replaced by semi colons. So the final results looks like *query;tag19=1;tag119=1;catint5=And;tag133=1;tag14=0;tag132=1*.
+
 ##CREATING AND UPDATING ENTITIES##
 
 When updating an entity through a PUT method, or creating an entity through a POST method, it is possible to also create and remove relationships.

WikiPage REST Interface modified by Matthew Casperson

Matthew Casperson — Tue, 24 Jan 2012 03:37:08 -0000

--- v21 
+++ v22 
@@ -26,6 +26,18 @@
 
 Secondary entities (i.e. those on the many side of a one-to-many relationship) do not have POST methods, because they can not exist without a primary entity. They can be created through the POST or PUT methods of their parents. See **CREATING AND UPDATING ENTITIES** for more information.
 
+###ADDITIONAL METHODS FOR TOPICS###
+
+Topic entities have a number of additional GET methods over the other primary entities.
+
+* /topics/get/atom/{query} - Returns the result of a query in the ATOM format
+* /topics/get/json/{query} - Returns the result of a query in the JSON format
+* /topics/get/xml/all - Returns all topics in the XML format
+* /topic/get/xml/{id} - Returns a single topic in the XML format
+* /topic/get/xml/{id}/xml - Returns the XML content of a single topic
+* /topic/get/xml/{id}/xmlContainedIn - Returns the XML content of a topic enclosed in a new XML element supplied by the **container** query parameter
+* /topic/get/xml/{id}/xmlNoContainer - Returns the XML content of a topic without the root section element, and without the title element if the **includeTitle** query parameter is set to false
+
 ##CREATING AND UPDATING ENTITIES##
 
 When updating an entity through a PUT method, or creating an entity through a POST method, it is possible to also create and remove relationships.