Skip to content

Latest commit

 

History

History
661 lines (469 loc) · 14.1 KB

README.md

File metadata and controls

661 lines (469 loc) · 14.1 KB
                __  __                      __    __  __            __
   ____  ____ _/ /_/ /_  ____ _____        / /_  / /_/ /_____  ____/ /
  / __ \/ __ `/ __/ __ \/ __ `/ __ \______/ __ \/ __/ __/ __ \/ __  / 
 / / / / /_/ / /_/ / / / /_/ / / / /_____/ / / / /_/ /_/ /_/ / /_/ /  
/_/ /_/\__,_/\__/_/ /_/\__,_/_/ /_/     /_/ /_/\__/\__/ .___/\__,_/   
                                                     /_/

nathan-httpd exposes a http based REST-like interface to nathan.

Quick Example

  1. Create bucket test

    PUT /test/ HTTP/1.0
    HTTP/1.1 204 No Content
Location: /test
Date: <date>

  2. Insert root context for document

    POST /test/_root HTTP/1.0
Content-Type: application/json
Content-Length: <length>

["doc1"]
    HTTP/1.1 201 Created
Location: /test/_1
Date: <date>
Content-Type: application/json
Content-Length: <length>

"_1"

  3. Insert paragraphs to document

    POST /test/_1 HTTP/1.0
Content-Type: application/json
Content-Length: <length>

[["hello","world"],["foo","bar"]]
    HTTP/1.1 201 Created
Location: /test/_1
Date: <date>
Content-Type: application/json
Content-Length: <length>

["_3","_5"]

  4. Get keywords of document 1

    POST /test/_1/keywords HTTP/1.0
Content-Type: application/json
Content-Length: <length>

{}
    HTTP/1.1 200 OK
Date: <date>
Content-Type: application/json
Content-Length: <length>

[["hello",100,20],["world",99,10],...]

Todo

  • Add /:bucket/:fetch?handles=handle0,handle1,... ressource for fetching multiple contexts based on handles
  • Evaluate some kind of master-slave synchronization facility to strengthen availability and data safety.
  • Add description for analysis response format.
  • Discuss more complex query functionality (batch processing, complex selections, association trees, etc.).

Ressources

Bellow you find the different ressources the API has and the verbs that can be executed. You are looking at version 1 of the API.

/

[GET] List buckets

Description

Lists existing buckets.

/:bucket

[POST] Query bucket

Description

TBD

[GET] Download dataspace

Description

Download the dataspace at /:bucket.

[PUT] Create or replace dataspace

Description

Replace the dataspace at /:bucket.

[DELETE] Delete dataspace

Description

Deletes bucket /:bucket.

/:bucket/:handle

A handle uniqly identifies a context in the bucket. It has the form _HEX, where HEX is a hexadecimal number. Special handle _root identifies the root node of the bucket.

[POST] Insert context(s)

Description

Inserts context(s) as children of /:bucket/_root or /:bucket/:handle.

Examples

  • Append single root context:

     POST /test/_root HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>
 
 ["doc1"]
     HTTP/1.1 201 Created
 Location: /test/_1
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>
 
 "_1"

  • Append single child context:

     POST /test/2b HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 ["hello","world"]
     HTTP/1.1 201 Created
 Location: /test/_2d
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 "_2d"

  • Bulk append child contexts:

     POST /test/_2b HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 [["hello","world"],[1,2,3,4]]
     HTTP/1.1 201 Created
 Location: /test/fetch?handles=_2d,_2f
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 ["_2d","_2f"]

Dicussion

  • Add line delimited JSON stream instead of arrays for multi insert (http://en.wikipedia.org/wiki/Line_Delimited_JSON).

     POST /test/2b HTTP/1.0
 Content-Type: application/x-ldjson
 Content-Length: <length>

 ["hello","world"]
 [1,2,3,4]
     HTTP/1.1 201 Created
 Location: /test/fetch?handles=_2d,_2f
 Date: <date>
 Content-Type: application/x-ldjson
 Content-Length: <length>

 "_2d"
 "_2f"

  • Allow insert of more complex contexts (e.g. objects, etc.)

[GET] Fetch Context

Description

Fetches context of /:bucket/:handle.

See also

To bulk fetch multiple context see /:bucket/fetch.

Examples

  • Fetch context _1c:

     GET /test/_1c HTTP/1.0
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 ["foo","bar"]

  • Fetch root (returns bucket name):

     GET /test/_root HTTP/1.0
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 "test"

[PUT] Replace context

Description

Replaces context at /:bucket/:handle.

Scope

Not allowed on /:bucket/_root.

Example

  • Replace context _2b:

     PUT /test/_2b HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 ["foo","bar"]
     HTTP/1.1 204 No Content
 Date: <date>

[DELETE] Remove context

Description

Removes context at /:bucket/:handle.

Scope

Not allowed on /:bucket/_root.

Example

  • Delete context _2b:

     DELETE /test/_2b HTTP/1.0
     HTTP/1.1 204 No Content
 Date: <date>

/:bucket/:handle/find

Find allows to query child contexts of either the _root handle or another context handle.

[POST] Query children

Description

Queries children contexts of /:bucket/:handle or of root /:bucket.

Payload

Request

{								// default values:
								//
	"filter": <query>,			// <query> = undefined
								//
	"take": <num>,				// <num> = 128
								//
	"skip": <num>,				// <num> = 0
								//
	"fetchContext": true|false	// <fetchContext> = false
}

Caption

  • filter — Filters children by their context, possible queries: {"$and": ["foo", "bar"]} (Match all), {"$or": ["foo", "bar"]} (Match some), {"$match": ["foo", "bar"]} (Match exactly).
  • take — Only return <num> results. Default is 128.
  • skip — Skip first <num> results. Default is 0.
  • fetchContext — enables/disables fetch of child contexts, default is false.

Examples

  • Query all root contexts:

     POST /test/_root/find HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 {}
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 ["_1", "_3", "_f"]

  • Query all children of _2b:

     POST /test/_2b/find HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 {}
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 ["_3a", "_3c", "_12"]

  • Query and fetch 10 children of _2b where context contains "hello" and "bar":

     POST /test/_2b/find HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 {"filter": {"$and": ["hello", "bar"]}, "take": 10}
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 [["foo","hello","bar"],[1,2,"hello",3.14159,"bar"],...]

/:bucket/:handle/keywords

Keywords allows to retrieve a sorted list of the most important terms of a context and its subcontexts.

[POST] Query keywords

Description

Retrieves a list of keywords of /:bucket/:handle.

Scope

Not allowed on /:bucket/_root.

Payload

Request

{								// default values:
								//
	"scope": <handles>,			// <handles> = undefined (all)
								//
	"sort": <order>,			// <order> = [-1,-1]
								//
	"cutoff": <threshold>		// <threshold> = [0,0]
								//
	"take": <num>,				// <num> = 128
								//
	"skip": <num>,				// <num> = 0
}

Caption

  • scope — Optional. Sets the scope of the command to the specified child (e.g. [ "_10c", "_2b", "_f4" ]).
  • sort — Optional. Sort result according specified : 1 = ascending, -1 = descending. Order can be set with [<p>,<v>] where <p> specifies order of vicinity value and v specifies order of vicinity value. To change order of sort key use [{"v": <v>},{"p": <p>}].
  • cutoff — Optional. Sets [<p>,<v>] (<p> = vicinity cut-off, v = plausibility cut-off). Default is [0,0].
  • take — Optional. Only return <num> results. Default is 128.
  • skip — Optional. Skip first <num> results. Default is 0.

Examples

  • Query keywords of _2c with default parameters:

     POST /test/_2c/keywords HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 {}
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 [["hello",100,20],["foo",99,10],...]

  • Query keywords of _4c with scope set to ["_4f", "_5d"] and cut-off on plaubility set to 10:

     POST /test/_4c/keywords HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 {"scope":["_4f","_5d"],"cutoff":[10,0]}
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 [["hello",100,20],["world",99,10],...]

/:bucket/associations

[POST] Query assocations

Description

Finds associations to the search terms.

Payload

Request

{								// default values:
								//
	"terms": <quants>			// <quants> required. No default value.
								//
	"direction": <dir>			// <dir> = 0 (forward)
								//
	"scope": <handles>,			// <handles> = undefined (all)
								//
	"sort": <order>,			// <order> = [-1,-1]
								//
	"cutoff": <threshold>		// <threshold> = [0,0]
								//
	"take": <num>,				// <num> = 128
								//
	"skip": <num>,				// <num> = 0
}

Caption

  • terms - Required. Specifies the search terms, e.g. ["green", "smooth"].
  • direction - Optional. Specifies the direction of the associations whereas 0 = forward and 1 = reverse.
  • scope — Optional. Sets the scope of the command to the specified child (e.g. [ "_10c", "_2b", "_f4" ]).
  • sort — Optional. Sort result according specified : 1 = ascending, -1 = descending. Order can be set with [<p>,<v>] where <p> specifies order of vicinity value and v specifies order of vicinity value. To change order of sort key use [{"v": <v>},{"p": <p>}].
  • cutoff — Optional. Sets [<p>,<v>] (<p> = vicinity cut-off, v = plausibility cut-off). Default is [0,0].
  • take — Optional. Only return <num> results. Default is 128.
  • skip — Optional. Skip first <num> results. Default is 0.

Example

  • Query associations for ["green", "smooth"]:

     POST /test/associations HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 {"terms":["green", "smooth"]}
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 [["apple",230,44],["green",97,44],...]

/:bucket/phonetic

[POST] Query phonetic similarities

Description

Finds similar terms for the search term.

Payload

Request

{								// default values:
								//
	"term": <quant>				// <quant> required. No default value.
								//
	"scope": <handles>,			// <handles> = undefined (all)
								//
	"sort": <order>,			// <order> = [-1,-1]
								//
	"cutoff": <threshold>		// <threshold> = [0,0]
								//
	"take": <num>,				// <num> = 128
								//
	"skip": <num>,				// <num> = 0
}

Caption

  • term - Required. Specifies the search term, e.g. "aple".
  • scope — Optional. Sets the scope of the command to the specified child (e.g. [ "_10c", "_2b", "_ff4" ]).
  • sort — Optional. Sort result according specified : 1 = ascending, -1 = descending. Order can be set with [<p>,<v>] where <p> specifies order of vicinity value and v specifies order of vicinity value. To change order of sort key use [{"v": <v>},{"p": <p>}].
  • cutoff — Optional. Sets [<p>,<v>] (<p> = vicinity cut-off, v = plausibility cut-off). Default is [0,0].
  • take — Optional. Only return <num> results. Default is 128.
  • skip — Optional. Skip first <num> results. Default is 0.

Example

  • Query similar terms for "aple" take 5 results:

     POST /test/phonetic HTTP/1.0
 Content-Type: application/json
 Content-Length: <length>

 {"term":["aple"],"take":5}
     HTTP/1.1 200 OK
 Date: <date>
 Content-Type: application/json
 Content-Length: <length>

 [["apple",210,66],...]