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

Docker

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=<number>

You can stop all containers with make stop.

Manual

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_<NUM>_TCP_ADDR
• port: $DB_PORT_<NUM>_TCP_PORT
• user: $DB_ENV_USER
• password: $DB_ENV_PASSWORD

License

MIT