tiq-server

tiq-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
-----

$3

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.

$3

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
(where $XDG_CONFIG_HOME 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".
[default: "pg"]
- 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__TCP_ADDR
- port: $DB_PORT__TCP_PORT
- user: $DB_ENV_USER
- password: $DB_ENV_PASSWORD`

License
-------

MIT