<
From version < 33.1 >
edited by Vincent Massol
on 2011/10/20
To version < 34.1 >
edited by Fabio Mancinelli
on 2011/11/08
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.VincentMassol
1 +XWiki.fmancinelli
Content
... ... @@ -4,8 +4,6 @@
4 4  
5 5  XWiki provides fine-grain access to virtually every element through an API that is based on HTTP semantics, i.e., a RESTful API. In this page you will find all the details to take advantage of this API and the instructions to use it at its full potential.
6 6  
7 -See also this [[tutorial by Fabio Mancinelli>>http://blog.fabiomancinelli.org/2011/03/07/XWikis_RESTful_API.html]].
8 -
9 9  = Accessing the service =
10 10  
11 11  By defaut the XWiki RESTful API entrypoint is rooted at the following URI:
... ... @@ -875,3 +875,79 @@
875 875  The name of the component has to be the class FQN.
876 876  
877 877  You can find more examples on [[https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-rest/xwiki-platform-rest-server/src/main/java/org/xwiki/rest/resources]].
876 +
877 += Using the RESTful API =
878 +
879 +== Highlevel description and tutorial for a basic usage of the RESTful API ==
880 +
881 +See this [[tutorial by Fabio Mancinelli>>http://blog.fabiomancinelli.org/2011/03/07/XWikis_RESTful_API.html]].
882 +
883 +== Creating an Object ==
884 +
885 +In this example we will use the [[curl>>http://curl.haxx.se/]] utility as the HTTP client.
886 +
887 +Imagine that you want to create on the page Test.Test a new object of the class XWiki.TestClass, supposing that the class has a text property.
888 +
889 +So, on the command line, you have to do the following:
890 +
891 +{{code}}
892 +$ curl -u Admin:admin
893 + -X POST
894 + -H "Content-type: application/xml"
895 + -H "Accept: application/xml"
896 + -d "@test.xml"
897 + http://localhost/xwiki/rest/wikis/xwiki/spaces/Test/pages/Test/objects
898 +{{/code}}
899 +
900 +where ##test.xml## is:
901 +
902 +{{code language="xml"}}
903 +<object xmlns="http://www.xwiki.org">
904 + <className>XWiki.TestClass</className>
905 + <property name="Text">
906 + <value>Whatever you want to put here</value>
907 +</property>
908 +</object>
909 +{{/code}}
910 +
911 +Alternatively you can use the less verbose ##application/x-www-form-urlencoded format##:
912 +
913 +{{code}}
914 +$ curl -u Admin:admin
915 + -X POST
916 + -H "Content-type: application/x-www-form-urlencoded"
917 + -H "Accept: application/xml"
918 + -d "@test.txt"
919 + http://localhost/xwiki/rest/wikis/xwiki/spaces/Test/pages/Test/objects
920 +{{/code}}
921 +
922 +where ##test.txt## contains something like:
923 +
924 +{{code}}
925 +className=XWiki.TestClass&property#Test=Whatever+you+want
926 +{{/code}}
927 +
928 +Or, better, you can use directly curl to specify these parameters
929 +using multiple ##-d## switches:
930 +
931 +{{code}}
932 +$ curl -u Admin:admin
933 + -X POST -H "Content-type: application/x-www-form-urlencoded"
934 + -H "Accept: application/xml"
935 + -d "className=XWiki.TestClass"
936 + -d "property#Test=Whatever you want"
937 + http://localhost/xwiki/rest/wikis/xwiki/spaces/Test/pages/Test/objects
938 +{{/code}}
939 +
940 +The advantage of the second approach is that curl will take care of url-encode your content, while if you send a file you are responsible for this.
941 +
942 +=== Remarks:
943 +
944 +* In the ##application/x-www-form-urlencoded## format the "property#" is a standard immutable prefix that is used to distinguish attributes referring to property values from the attributes referring to the object. For example if we had ##className=XYZ&Text=FOO## we would have had an ambiguity on ##className## because we couldn't understand if ##className## is a property of the object to be set to XYZ or an attribute that describes the object itself (i.e., its metadata like the ##className##). By having the ##property~### prefix this ambiguity is resolved.
945 +
946 +* The information you get back when you retrieve an object (i.e., all
947 +the ##<attribute>## elements) are useful when clients need to understand the type of data contained in an object (e.g., when they want to display it). They are not necessary when creating an object because the system already has this information. That's why the XML to be sent is smaller. Actually the only information needed is the ##<className>## and a set of ##<property name="..."><value>## elements.
948 +
949 +* How do you know what kind of information you can send with the XML? You can discover it by using the class description URI. If you go to ##http://localhost:8080/xwiki/rest/wikis/xwiki/classes ## you will get a list of all the classes defined in the Wiki. By looking at this you will understand what are the properties defined by each class, their types and attributes. In that way you will know what you're allowed to put in the ##<property><value>## elements of the XML you send.
950 +
951 +

Get Connected