jacobshuman/readl8r repository overview

⁠readl8r

⁠⭐️ Features

• ➕ Add an article by making a POST request (with url in a JSON body) to /articles/add.
• 📋 Get a JSON array of all articles by making a GET request to /articles.
• 🗑️ Remove all articles by making a DELETE request to /articles/clear.
• 🗄️ All articles are stored in a /data/local.sqlite SQLite database.
• 📥 Get an RSS⁠, Atom⁠, and JSON⁠ feed of articles at /rss, /atom, and /json respectively.

⁠🚀 Getting started

⁠🚢 Docker Compose

Although you can clone/build readl8r locally, it's recommended for users to run the docker image on Docker Hub⁠. Copy the contents of this docker-compose.yml⁠ file to your computer and run:

docker compose up

⁠🌴 Environment variables

⁠🔒 Authentication

You can optionally protect your reading list with a password by setting the PASSWORD and AUTH_SECRET environment variables in your docker compose config.

This will protect all routes excluding feed routes (/rss, /atom, etc).

I'm still looking into how rss aggregators generally handle auth for feeds and only want to add auth when it doesn't prevent aggregators from accessing reading lists.

⁠Stucture of an article

{
	id: number;
	url: string;
	publish_date: string; // date article was published (added_date if this can't be found)
	added_date: string; // date the article was added to readl8r
	title: string | null;
	description: string | null;
	content: string | null;
	author: string | null;
	favicon: string | null;
	ttr: number | null; // estimated time to read article in seconds
}

⁠➕ Add an article

🔒 Requires Authentication

You can add an article by providing the article's url in the body of a POST request:

POST (http|https)://HOST:PORT/articles/add

⁠🏋️ body

{
	// required
	"url": "https://dev.to/jacobshuman/wtf-is-a-github-profile-readmemd-1p8c"
}

⁠Responses

⁠📄 Get a single JSON article

🔒 Requires Authentication

You can get a single JSON object representing an article by making a GET request to the /articles/:id route:

GET (http|https)://HOST:PORT/articles/:id

⁠Responses

⁠📋 Get a JSON array of all articles

🔒 Requires Authentication

You can get a JSON array of articles by making a GET request to the /articles route:

GET (http|https)://HOST:PORT/articles

⁠Responses

⁠📝 Update an article

🔒 Requires Authentication

You can update an article based on it's id by making a PATCH request to the /articles/:id/update route:

PATCH (http|https)://HOST:PORT/articles/:id/update

⁠🏋️ body

{
	"article": {
		"url": "", // optional
		"publish_date": "", // optional
		"added_date": "", // optional
		"title": "", // optional
		"description": "", // optional
		"content": "", // optional
		"author": "", // optional
		"favicon": "", // optional
		"ttr": "" // optional
	}
}

⁠Responses

⁠🗑️ Delete an article

🔒 Requires Authentication

You can delete an article based on it's id by making a DELETE request to the /articles/:id/delete route:

DELETE (http|https)://HOST:PORT/articles/:id/delete

⁠Responses

⁠🗑️ Remove all articles

🔒 Requires Authentication

DELETE (http|https)://HOST:PORT/articles/clear

⁠Responses

⁠🗑️ Purge old articles

🔒 Requires Authentication

You can manually purge articles older than a certain threshhold using the /articles/purge route. Simply pass an older_than query parameter in the url with the following format:

h = hours
d = days
m = months
y = years

<integer>h|d|m|y

Examples

30d = 30 days
4m  = 4 months
2y  = 2 years

DELETE (http|https)://HOST:PORT/articles/purge?older_than=<number>(h|d|m|y)

⁠Responses

⁠📥 Generate RSS2 feed from articles

GET (http|https)://HOST:PORT/rss

GET (http|https)://HOST:PORT/rss.xml

GET (http|https)://HOST:PORT/feed

GET (http|https)://HOST:PORT/feed.xml

⁠Responses

⁠📥 Generate Atom feed from articles

GET (http|https)://HOST:PORT/atom

⁠Responses

⁠📥 Generate JSON feed from articles

GET (http|https)://HOST:PORT/json

⁠Responses

⁠❤️ Health

A simple GET route to see if the server is up and ready to handle incoming requests.

GET (http|https)://HOST:PORT/health

⁠Responses