[Attempto] A RESTful api for AceWiki

[Changyuan Yu]

Hi Tobias Kuhn,
  Currently my code is not ready fore pull into main AceWiki, at least
some clear up are necessary.
  I think, using APESocket as alternative way to interactive with
ape.exe and add OSGi meta info into web.xml should be relatively
simple to merge into main AceWiki code, but other changes should be
more carefully consider and test before pull into upstream. So my will
focus on the first two changes.
  And here are some question to ask before I can do actual code clear up:
1. Are there any code style guideline for AceWiki? My coding style is
different from upstream(should I change or just keep?):
   (a) always use space instead of tab, and every tab is replaced with 4 spaces.
   (b) using different indent style, see:
http://en.wikipedia.org/wiki/Indent_style#Compact_Control_Readability_style
2. There is no any documentation in my code, is there any guideline
for documentation?

On Thu, Dec 8, 2011 at 9:31 PM, Tobias Kuhn <kuhntobias at gmail.com> wrote:
> Hi Changyuan,
>
> This all looks very interesting. Good work!
>
> If you are interested and if you have AceWiki extensions that could be of
> interest to others, you can file a pull request for the main AceWiki code
> base on GitHub. If your extensions are reasonably stable and do not affect
> existing features and behavior of AceWiki (e.g. must be activated with a
> parameter value), I would be glad to include them into the main branch.
>
>
> Regards,
> Tobias
>
>
>
>
> On 07.12.2011 12:53, Changyuan Yu wrote:
>>
>> Before show how the RESTful api works, I want to make some explanation
>> about the changes of the code.
>>
>> 1. Using APESocket instead of APELocal to call APE. On my
>> system(Gentoo amd64), every time upgrade swi-prolog, I must
>> reconfigure tomcat to make JPL work(libjpl.so location changes). And
>> if I compile swi-prolog as static binary and library, then tomcat will
>> crash. Current code initialize APESocket with fix host and port(port
>> 2766 on localhost), so an instance of ape.exe must run in socket
>> server mode to make AceWiki work.
>>
>> 2. Make the war be able to deployed in an OSGi container
>> (apache-karaf), compare to tomcat, apache-karaf is easier to use. I
>> can start, stop and re-deploy the war in karaf shell. To achieve this
>> goal, I modify the build.xml to add some information into
>> META-INF/MANIFEST.MF during build process.
>>
>> 3. Create a  servlet(RestServlet), which accept all AceWikiServlet
>> init parameters, and will handle all RESTful request. The servlet will
>> do all initialization(create ontology, save parameters, etc.) except
>> UI, store those initialized object into an object of class Backend,
>> and the store the object(of Backend class) into servlet context to
>> share with AceWikiServlet.
>>
>> 4. Mofidy AceWikiServlet and related class, first get an object of
>> Backend class(call it backend) from servlet context(use "backend"
>> paramter to determine from which RestServlet), then using ontology,
>> parameters and other objects from backend to create new classes.
>>
>> 5. Modify WEB-INF/web.xml, create two servlet instance of class
>> RestServlet, provide Backend object for two AceWikiServlet. Move all
>> parameters from AceWikiServlet to RestServlet, and add "backend"
>> parameter to AceWikiServlet with its value equal to corresponding
>> RestServlet name.
>>
>> 6. All actual wiki functions are done in Handler class. Current
>> implementation borrow a lot of code from UI part of AceWiki, and mix
>> wiki content maintain function with JSON object generation for fast
>> implementation.  There should be an spec of high level AceWiki content
>> maintain functions(and be implemented independent of actual UI), and
>> the RESTful web service should build up on this spec(we can see this
>> as another kind of "UI"). The web UI can also build up on the RESTful
>> api with ajax.
>>
>>
>> Now, I will show the detail of how to deploy the war and test the RESTful
>> api:
>>
>> First, build and deploy acewiki,
>> 1. Install necessary tools, including git, java, ant and curl, and
>> also ape.exe.
>> 2. clone dev branch of  AceWiki: git clone
>> https://github.com/yuchangyuan/AceWiki.git -b dev
>> 3. build the war with command "ant",  and file "acewiki.war" will be
>> created after the build process.
>> 4. deploy the war into any servlet container(tomcat, jetty,
>> apache-karaf etc), no need of special settings.
>> 5. run ape.exe as socket server.
>> 6. test AceWiki, when deploy in apache-karaf, the first demo wiki will
>> be on URL: localhost:8181/acewiki/acewiki/, other container may be has
>> a different URL.
>>   7. add some word and statement to AceWiki.
>>
>> Then, using curl command to test RESTful api,
>>
>> 1. when deploy in apache-karaf, the URL of first demo wiki should be
>> on URL: localhost:8181/acewiki/api/ (other container may be has a
>> different URL). For simplicity, I will just use this URL in following
>> commands.
>>
>> 2. List all words, GET on root of URL will list all articles or search
>> by word. Just using command "curl localhost:8181/acewiki/api/" to list
>> all articles, if the wiki is empty, below result will return:
>>
>> {
>>   "result": "ok",
>>   "0": {
>>     "word": [],
>>     "type": "mainpage"
>>   }
>>
>> where, the "0" is the id of article, "word" is the words(I think I
>> should rename this to "words") of the article, and "type" is the type
>> of the article. Below is a more complex return with more words(and
>> more type):
>>
>> {
>>   "result": "ok",
>>   "13": {
>>     "word": [
>>       "byte",
>>       "bytes"
>>     ],
>>     "type": "Noun"
>>   },
>>   "11": {
>>     "word": [
>>       "directory",
>>       "directories"
>>     ],
>>     "type": "Noun"
>>   },
>>   "12": {
>>     "word": [
>>       "file",
>>       "files"
>>     ],
>>     "type": "Noun"
>>   },
>>   "3": {
>>     "word": [
>>       "test-object1",
>>       "test-object1",
>>       "test-object1",
>>       "test-object1"
>>     ],
>>     "type": "Proper Name"
>>   },
>>   "2": {
>>     "word": [
>>       "test-object",
>>       "test-objects"
>>     ],
>>     "type": "Noun"
>>   },
>>   "1": {
>>     "word": [
>>       "object",
>>       "objects"
>>     ],
>>     "type": "Noun"
>>   },
>>   "10": {
>>     "word": [
>>       "apple",
>>       "apples"
>>     ],
>>     "type": "Noun"
>>   },
>>   "0": {
>>     "word": [],
>>     "type": "mainpage"
>>   },
>>   "7": {
>>     "word": [
>>       "color",
>>       "colors"
>>     ],
>>     "type": "Noun"
>>   },
>>   "6": {
>>     "word": [
>>       "path of"
>>     ],
>>     "type": "Of-Construct"
>>   },
>>   "5": {
>>     "word": [
>>       "Dir1",
>>       "Dir1",
>>       "Dir1",
>>       "Dir1"
>>     ],
>>     "type": "Proper Name"
>>   },
>>   "4": {
>>     "word": [
>>       "has",
>>       "have",
>>       "had by"
>>     ],
>>     "type": "Verb"
>>   },
>>   "9": {
>>     "word": [
>>       "color of"
>>     ],
>>     "type": "Of-Construct"
>>   },
>>   "8": {
>>     "word": [
>>       "red",
>>       "reds"
>>     ],
>>     "type": "Noun"
>>   }
>> }
>>
>>
>> For words search, just using 'search' as query key. For example,
>> search "by" with command
>> "curl 'localhost:8181/acewiki/api/?search=by'", will return
>> {
>>   "result": "ok",
>>   "4": {
>>     "word": [
>>       "has",
>>       "have",
>>       "had by"
>>     ],
>>     "type": "Verb"
>>   },
>>   "13": {
>>     "word": [
>>       "byte",
>>       "bytes"
>>     ],
>>     "type": "Noun"
>>   }
>> }
>>
>>
>> 3. Add statement, POST on an article to add a statement to the
>> article. The POST using a json encoded input data as argument. For
>> example,  command:
>>
>> curl -X POST localhost:8181/acewiki/api/0 -d '{"statement":"comment
>> 1", "comment":true, "commit":true, "position":2}'
>>
>> will create a comment "comment 1" as second statement of main page,
>> because main page has the id of 0, so I append 0 to the URL, and I
>> want to add the statement, so set "commit" to true. The return of
>> above command is:
>>
>> {
>>   "position": 2,
>>   "result": "ok",
>>   "valid": true,
>>   "complete": true,
>>   "candidates": {}
>> }
>>
>> because input "position" might be larger than total statement number
>> or be negative number (position from last statement), the return
>> "position" will show the actual position of newly created comment.
>>
>> For sentence, the "commit" has not yet be implemented(always treat as
>> false), but we can use it to find next possible word of a partial
>> sentence, or check whether a sentence is valid. For example, command
>>
>> curl -X POST localhost:8181/acewiki/api/0 -d '{"statement":""}'
>>
>> will return a list of possible words to start a sentence, the return
>> will looks like:
>>
>> {
>>   "position": -1,
>>   "result": "ok",
>>   "valid": true,
>>   "remain": "",
>>   "complete": false,
>>   "tokens": [],
>>   "candidates": {
>>     "": [
>>       "less than",
>>       "somebody",
>>       "there are",
>>       "every",
>>       "an",
>>       "at most",
>>       "which",
>>       "no",
>>       "a",
>>       "nothing",
>>       "what",
>>       "for every",
>>       "more than",
>>       "everything",
>>       "it is false that",
>>       "if",
>>       "exactly",
>>       "everybody",
>>       "there is",
>>       "something",
>>       "at least",
>>       "who",
>>       "nobody"
>>     ],
>>     "propername": [
>>       "test-object1",
>>       "Dir1"
>>     ],
>>     "variable": [
>>       "Y",
>>       "Z",
>>       "X"
>>     ]
>>   }
>> }
>>
>> And for get next possible word after "an apple", using below command:
>> curl -X POST localhost:8181/acewiki/api/0 -d '{"statement":"an apple"}'
>> and will return:
>>
>> {
>>   "position": -1,
>>   "result": "ok",
>>   "valid": true,
>>   "remain": "",
>>   "complete": false,
>>   "tokens": [
>>     "an",
>>     "apple"
>>   ],
>>   "candidates": {
>>     "": [
>>       "that",
>>       "who",
>>       "which",
>>       "is",
>>       "is not",
>>       "does not"
>>     ],
>>     "verbsg": [
>>       "has"
>>     ],
>>     "variable": [
>>       "Z",
>>       "X",
>>       "Y"
>>     ]
>>   }
>> }
>>
>> Also, for test whether a sentence(or part of sentence) is valid,
>> curl -X POST localhost:8181/acewiki/api/0 -d '{"statement":"a apple not
>> fruit"}'
>> and will return:
>>
>> {
>>   "position": -1,
>>   "result": "ok",
>>   "valid": false,
>>   "remain": "not fruit",
>>   "complete": false,
>>   "tokens": [
>>     "a",
>>     "apple"
>>   ],
>>   "candidates": {}
>> }
>>
>>
>> Above are all what currently implemented, and maybe there are bugs.
>>  From now on, I will stop the java development for a while and begin to
>> create a simple emacs mode to interactive with the RestServlet and
>> test the word predictive function.
>>
>>
>> On Wed, Dec 7, 2011 at 3:50 PM, Tobias Kuhn<kuhntobias at gmail.com>  wrote:
>>>
>>> Hi,
>>>
>>>>   After several days of trying AceWiki and reading its code, I want to
>>>> share some feelings and ideas about AceWiki.
>>>
>>>
>>>
>>> Thanks for sharing! It looks very interesting.
>>>
>>>
>>>>   In order to make this happen, AceWiki should split into two part,
>>>> the UI part which most in ch.uzh.ifi.attempto.acewiki.gui package (or
>>>> call it front end) and the actual function part which do all other
>>>> things except UI (or call this back end part).
>>>
>>>
>>>
>>> Yes, you are right. Model and view and not separated as they should be.
>>> This
>>> wasn't a problem so far, because there was only one GUI, but it's not so
>>> nice conceptually.
>>>
>>>
>>>>   So I fork AceWiki on github and begin to implement my ideas, I
>>>> choose RESTful style api for expose the wiki function, and now below
>>>> functions are implemented(just verified using very simple test),
>>>> 1. list all articles or search by word.
>>>> 2. add comment to an article.
>>>> 3. find candidate words for a partial sentence.
>>>
>>>
>>>
>>> Very nice! Can you give a couple of concrete examples?
>>>
>>>
>>>> And finally, the code: https://github.com/yuchangyuan/AceWiki/tree/dev
>>>
>>>
>>>
>>> For those interested, this page shows the changes to the latest version
>>> of
>>> AceWiki:
>>>
>>> https://github.com/yuchangyuan/AceWiki/compare/AceWiki:master...yuchangyuan:dev
>>>
>>>
>>> Regards,
>>> Tobias