JsonAPI.txt

= ninuXoo JSON API =

== Search Operations ==

Operation: exactquery 
Description: return the search results that match exactly (i.e. performing an
AND between the exact words) <querystring>.
The optional parameter "ip" restricts the search to a given server IP address.
The optional parameter "filetype" restricts the search to a given filetype/extension.
URL: /json.cgi?op=exactquery&q=<querystring>&ip=<IP address>&filetype=<extension>

Operation: orquery
Description: return the search results that match the single exact words in
<querystring>.
The optional parameter "ip" restricts the search to a given server IP address.
The optional parameter "filetype" restricts the search to a given filetype/extension.
URL: /json.cgi?op=orquery&q=<querystring>&ip=<IP address>&filetype=<extension>

Operation: likequery
Description: return search results by performing variations on the words in
<querystring>, limiting to no more than <word limit> words.
The optional parameter "ip" restricts the search to a given server IP address.
The optional parameter "filetype" restricts the search to a given filetype/extension.
URL: /json.cgi?op=likequery&q=<querystring>&words=<word limit>&ip=<IP address>&filetype=<extension>

Operation: query 
Description: return search results by applying in order the exactquery, orquery
and likequery operations, trying to retrieve at least <nresults> results.
The optional parameter "ip" restricts the search to a given server IP address.
The optional parameter "filetype" restricts the search to a given filetype/extension.
URL: /json.cgi?op=query&q=<querystring>&nresults=<nresults>&ip=<IP address>&filetype=<extension>
NOTES: nresults default is 200

Operation: whatsnew 
Description: return the resources that have been recently discovered, trying to
retrieve at least <nresults> results, but no more than <nresults>
URL: /json.cgi?op=whatsnew&nresults=<nresults>
NOTES: nresults default is 200

Operation: serverlist
Description: return the list of found servers
URL: /json.cgi?op=serverlist

== Search Results Format ==

{
    responsen: <response number>,
    response: <response description>,
    q: <search terms>,
    nresults: <number of results>,
	nlabels: <number of result labels>,
	searchtime: <search time>,
    results: [
               {
               resultlabel: <results label>,
               exactresult: <exact result flag>,
               nresults: <number of results>,
               resourcetrie: {
                           label: <label>,
                           rank: <hierarchy rank>,
                           resources: [
                                {
                                    uri: <resource URI>,
                                    filename: <file name>,
                                    filetype: <file type>
                                },
                                {
                                    uri: <resource URI>,
                                    filename: <file name>,
                                    filetype: <file type>
                                },
                                ...
                           ],
                           children: [
                                {
                                    label: <label>,
                                    rank: <hierarchy rank>,
                                    resources [
                                       ...
                                    ],
                                    children: [
                                       ...
                                    ]
                                },
                                {
                                    label: <label>,
                                    rank: <hierarchy rank>,
                                    resources {
                                       ...
                                    },
                                    children: {
                                       ...
                                    }
                                },
                                ...
                           ]
               }
         },
         {
               resultlabel: <results label>,
               exactresult: <exact result flag>,
               nresults: <number of results>,
               resourcetrie: {
                      ...
               }
         },
         ...
    ]
}


response number: 200 -> OK, 400 -> bad request, 418 -> i'm a teapot, 500 -> server error, 501 -> not implemented

response description: textual description of the response

number of result labels: number of set of results found

search time: time, in seconds, needed to perform the search

results label: the search term or terms that yield to the following results

exact result flag: true for "exact" result, false for "or" or "like" result

number of results: number of resources in the "resources" object

label: the (partial) path on the server

hierarchy rank: the level of the trie's hierarchy. The server's IP/hostname has rank = 2, while the protocol (e.g. "smb:") has rank = 1

resource URI: the resource's complete URI

file name: the resource's file name

file type: the resource's file type


== Other Operations ==

Operation: resourcestats
Description: return the total number of resources currently indexed by the search engine
URL: /json.cgi?op=resourcestats

Operation: serverstats
Description: return the total number of servers currently indexed by the search engine
URL: /json.cgi?op=serverstats

== Other Operations Response/Result Format ==

{
    responsen: <response number>,
    response: <response description>,
	result: <result>
}