shrty/README.md

# Shrty
Shrty is a lightwaight, self-hostable open-source link shortening web application with a Restful API. It allows you to host your own URL shortener to gain control over your data. Shrty is inspired by [Polr](https://polr.me/index.php), a php based url shortener.

## Features

- [x] No duplicated URL
- [x] Simple UI
- [x] Simple database Json file
- [x] Restful API
- [x] Simple Click Statistik
- [ ] Key protected API
- [ ] Nice overfewpage for shorted URLs
- [ ] Delete URL
- [ ] Login

## Installation

Clone the Repository and build the Application by using `go build .`

Start Shrty by the following commant `./sgot &`

|   Flag   |                 Usage                  |               Default                |
| -------- | -------------------------------------- | ------------------------------------ |
| -host    | setup the host to listen on            | localhost                            |
| -port    | Setup the port to listen on            | 6889                                 |
| -apikey  | Define the key to connect with the API | "thisIsNotASecretTokenNow"           |
| -db-file | Setup the DB file to use               | ./shrty.db                           |
| -title   | Service title                          | Shrty                                |
| -domain  | Domain for the redirection link        | The domain your service is available |

## API
To authenticate a user to Polr, you will need to provide an API key along with each request to the Polr API, as a GET or POST parameter. (e.g ``?key=API_KEY_HERE``)


### /api/v1/action/shorten

Arguments:

* ``url``: the URL to shorten (e.g https://google.com)
* ``custom_ending`` [not now supported] (optional): a custom ending for the short URL. If left empty, no custom ending will be assigned.

Short an URL
```
GET: http://example.com/api/action/shorten?key=API_KEY_HERE&url=http://example.de/shortening/main?q=5x

Response:
{ "action": "shorten",
  "result": "https://example.com/5kq" }
```

### /api/v1/action/lookup

Arguments:

* ``url_ending``: the link ending for the URL to look up. (e.g 5ga)

Lookup for existing URL

```
GET: http://example.com/api/action/lookup?key=API_KEY_HERE&url_ending=5kq

Response:
{ "action":"lookup",
  "result": {
        "long_url": "http://example.de/shortening/main?q=5x",
        "created_at": "2017-05-12 22:48:40.997520107 +0200 CEST",
        "clicks":"0"
        }
}
```

## ToDo

* Add more Statistik details like the clicks from Country and Referer.
* Implements the correct HTTP Error Codes
* Add config File
* Secure the API with API Key [optional]