A microservice for providing a random link from a curated collection, written in Clojure. Technically, it does not have to be a link, just an arbitrarily short string (i.e., less than 256 characters). Access is in the form of HTML-based JSON and responses are returned in the same manner.
- Simple API - JSON response containing "message" and "success?" fields.
- Allows updating of link collection by adding or deleting links.
It is perfect for those with a need to provide a random link on demand and via a service. The links can be easily tailored to your context and prefered content. For example, by implementing the API, the bot idling in Slack could provide a link or even update the collection of links straight from the chat.
We haven't quite found anything like link-service, but it is reasonable to expect something similar does exist. An early inspiration was pugme for Hubot.
If you know of a similar service or project then let us know and we'll add it here!
You will need Leiningen 2.0.0 or above installed.
There are a couple of different ways to use this service.
A simple uberjar that is ready to deploy might be the fastest way to test out link-service. All you need to do is provide some properties on launch. All properties except for -Dtokens have defaults and can be omitted. For instance:
java -Ddb.user=sa -Ddb.password=password1 -Dtokens=d89b060e,8sd1a2xb -jar link-service-0.1.0-SNAPSHOT-standalone.jar
| Property | Example | Optional | Default |
|---|---|---|---|
| -Ddb.user | sa | y | sa |
| -Ddb.password | password1 | y | |
| -Dtokens | d89b060e | n | required |
| -Dip | 192.168.1.252 | y | 0.0.0.0 |
| -Dport | 7999 | y | 8090 |
Note that -Dtokens should have a comma in between each token with no spaces.
Clone the project and in the project's directory run lein repl from the command line followed by (-main). Make sure you add a profiles.clj file as described below in Development Notes.
In order to interact with the service you will want to implement the API outlined below. Alternatively, you could use a browser plugin such as RESTED.
There are three endpoints /random, /add, and /delete. All communication to and from is through JSON. If you happen to use Clojure then check out the excellent Cheshire for JSON encoding/decoding.
To send a request for a link, use a GET request against /random. Make sure the Content-Type of your header is correct. It should be application/json.
To access the content returned from /random, you can parse the body. It should just be a JSON map like the following example:
{
"message": "https://github.com/ring-clojure/ring"
}To add content, you can use /add and send a POST with a JSON body as follows:
{
"message": "https://github.com/ring-clojure/ring",
"token": "d89b060e"
}The keys used are "message": string, "token": string, "success?": boolean.
Deleting content works the same way as /add but with the endpoint /delete.
Sending an invalid token will result in no changes and a message is returned stating failure.
The maximum link length is 255 characters.
This project was created to better provide random links of random things to random people. It was used to better understand certain libraries such as Ring, Compojure, and Korma. A secondary goal was to become familiar with Docker. More importantly, it was made to support a certain Slack bot's need for quality cat gifs acquired throughout the Internet.
To run tests: lein test
To run documentation generation: lein doc
To run the repl: lein repl
To package the uberjar: lein uberjar
Be sure to create and populate a file named profiles.clj at the root of the project directory. This file should contain various config info, such as the database user and password as well as tokens. The only required entry is the :tokens. You'll want to mimic the following, but with better passwords and tokens:
{:dev-overrides {:env {:ip "0.0.0.0"
:port 8090
:db-user "sa"
:db-password "password1"
:tokens ["aaaaaaaa"]}}
:test-overrides {:env {:ip "0.0.0.0"
:port 8090
:db-user "sa"
:db-password "password1"
:tokens ["bbbbbbbb"]}}
:uberjar-overrides {:env {:ip "0.0.0.0"
:port 8090
:db-user "sa"
:db-password "password1"
:tokens ["cccccccc"]}}}
- Tagging links so results can be returned based on tags.
- Dead link checking - periodically attempts to access the curated links and removes dead ones.
- Security features
- Export/dump link collection
If you plan to use this project, please keep in mind it was developed for my amuzement in my spare time and may have bugs, major design flaws, or other issues. That said, feel free to submit issues, pull requests, or questions. I am happy to assist.
Copyright © 2015 Scott Bauer
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.