npm install tiq-servertiq-server
==========
This is an HTTP API server for tiq.
It's essentially an HTTP interface to interacting with tiq data stored in
PostgreSQL using tiq-db.
Setup
-----
Clone this repo and run:
```
$ make build
This will download and setup three Docker containers
with Ubuntu 14.04: one for PostgeSQL, one for nginx and one for tiq-server.
To start the servers run:
``
$ make
... which will make tiq-server (proxied behind nginx) available on
http://localhost:8000/.
If you wish to change the port, run:
``
$ make PORT=
You can stop all containers with make stop.
This is more complicated, but essentially npm install -g tiq-server, install
PostgreSQL (and optionally nginx), and configure and start everything manually.
Save yourself the trouble, and just use Docker. :)
Usage
-----
The API accepts and returns only JSON encoded data.
Here's how you add some tags to some text:
`
POST / HTTP/1.1
Content-Type: application/json
{"tokens":["This too shall pass."],"tags":["quotes","inspiring"]}
`
To tag some URLs:
`
POST / HTTP/1.1
Content-Type: application/json
{"tokens":["http://duckduckgo.com/"],tags":["url","search","awesome"]}
`
`
POST / HTTP/1.1
Content-Type: application/json
{"tokens":["http://www.bing.com/"],"tags":["url","search","microsoft"]}
`
`
POST / HTTP/1.1
Content-Type: application/json
{"tokens":["http://www.reddit.com/"],"tags":["url","timewaster","funny"]}
`
Then, to recall stuff tagged with search:``
GET /?tags=search HTTP/1.1`
->`
{"status":"success","data":["http://duckduckgo.com/", "http://www.bing.com/"]}
... or both search and awesome:``
GET /?tags=search&tags=awesome HTTP/1.1`
->`
{"status":"success","data":["http://duckduckgo.com/"]}
Or to get the tags associated with a token:
``
GET /?tags=http://duckduckgo.com/ HTTP/1.1`
->`
{"status":"success","data":["url","search","awesome"]}
Note that the string MAY be encoded (e.g. /?tags=http%3A%2F%2Fduckduckgo.com%2F),
which should return the same result.
You can also tag multiple things at once:
`
POST / HTTP/1.1
Content-Type: application/json
{"tokens":["http://www.engadget.com/","http://www.theverge.com/"],"tags":["url","tech"]}
`
Doing the reverse is equivalent to the above:
`
POST / HTTP/1.1
Content-Type: application/json
{"tags":["http://www.engadget.com/","http://www.theverge.com/"],"tokens":["url","tech"]}
`
By default, the public namespace is used if none is specified. But you can`
use any other namespace you want to partition the data. For example:
POST /john HTTP/1.1
Content-Type: application/json
{"tokens":"http://myprivateblog.com/","tags":["url","blog"]}
`
Now to get things tagged with url under the john namespace:``
GET /john?tags=url HTTP/1.1`
->`
{"status":"success","data":["http://myprivateblog.com/"]}
Configuration
-------------
The configuration file by default is expected in $XDG_CONFIG_HOME/tiq-server/config.json$XDG_CONFIG_HOME
(where is $HOME/.config).
Here are the options you can set in the configuration file:
- port: The port the server will listen on. [default: 8000]database.client
- : The RDBMS client to use. One of "sqlite3", "pg" or "mysql"."pg"
[default: ]database.connection.host
- : Host name or IP address to connect to. [default: "localhost"]database.connection.port
- : Port to connect to. [default: 5432]database.connection.user
- : Username used to connect to the host. [default: null]database.connection.password
- : Password used to connect to the host. [default: null]database.connection.database
- : Database name to use. [default: "tiq"]
Essentially, everything under database is what tiq-db
expects.
You can also change some of these at runtime using environment variables that
follow Docker linking naming conventions:
- host: $DB_PORT_port
- : $DB_PORT_user
- : $DB_ENV_USERpassword
- : $DB_ENV_PASSWORD`
License
-------