@@ -5,6 +5,7 @@ SPDX-License-Identifier: CC0-1.0
-->
# earl
+
[![REUSE status][reuse-shield]][reuse]
[![Donate with fosspay][fosspay-shield]][fosspay]
![Time spent on project][wakapi-shield]
@@ -12,30 +13,36 @@ SPDX-License-Identifier: CC0-1.0
Personal shortlink generator
## Features
+
Links are …
+
- Editable
- Removable
- Four characters long (26 uppercase letters + 26 lowercase letters + 10 numbers
= 14,776,336 possible shortened URLs)
Service has …
+
- A simple API
- A simple web UI
- A simple backup procedure (database is a single directory)
-- No user management (this is a *personal* service after all)
+- No user management (this is a _personal_ service after all)
## API documentation
### `/create`
#### Required parameters
+
- `url`: percent-encoded URL being shortened
#### Optional parameters
+
- `name`: percent-encoded short link the `url` will be mapped to. If this is not
provided, a random, 4-character code will be generated instead.
#### Output
+
- `401 Unauthorized: You do not have permission to create shortlinks` if access
token provided in `Authorization` header does not match the configured access
token
@@ -47,17 +54,20 @@ Service has …
### `/read`
#### Required parameters
+
- None
#### Optional parameters
+
- None
#### Output
+
- `401 Unauthorized: You do not have permission to view shortlinks` if access
token provided in `Authorization` header does not match the configured access
token
-- JSON representation of the key/value database (200 OK)
- ``` json
+- JSON representation of the key/value database (200 OK)
+ ```json
{
"6H1g": "https://git.sr.ht/~amolith/earl/tree/dev",
"N3yg": "https://secluded.site/"
@@ -67,19 +77,22 @@ Service has …
### `/update`
#### Required parameters:
-- `oldName`: percent-encoded name the URL is *currently* referred to with
-- `name`: percent-encoded name the URL *will* be referred to with
+
+- `oldName`: percent-encoded name the URL is _currently_ referred to with
+- `name`: percent-encoded name the URL _will_ be referred to with
- `url`: percent-encoded URL being shortened
`name` and `url` are first set as a key/value pair. If `name` already exists,
-`url` is updated. If `name` does *not* already exist, it's created and `oldName`
+`url` is updated. If `name` does _not_ already exist, it's created and `oldName`
is deleted. If the user is only modifying `url`, `oldName` and `name` should
both be submitted but their values should be identical.
#### Optional parameters:
+
- None
#### Output:
+
- `401 Unauthorized: You do not have permission to create shortlinks` if access
token provided in `Authorization` header does not match the configured access
token
@@ -93,12 +106,15 @@ both be submitted but their values should be identical.
### `/delete`
#### Required parameters:
+
- `name`: percent-encoded short link
#### Optional parameters:
+
- None
#### Output:
+
- `401 Unauthorized: You do not have permission to create shortlinks` if access
token provided in `Authorization` header does not match the configured access
token
@@ -106,6 +122,7 @@ both be submitted but their values should be identical.
- `$URL has been deleted` (200 OK)
## But … why?
+
Good question. URL shorteners are (usually) terrible and useless. Except when
used correctly :thinkingsmart:
@@ -121,7 +138,7 @@ something like 6-character-long paths for the links as they're meant for use by
multiple people; 14.8m possible URLs (your cap with 4 character paths) aren't
enough for public services.
-Now six characters is *fine* but why write six characters when you could write
+Now six characters is _fine_ but why write six characters when you could write
four :D
And why deal with user management and a relational database when you're only
@@ -134,6 +151,7 @@ link tracking and a bunch of other crap I have no use for.
So I decided to make my own that has exactly what I want and nothing more :D
## Questions & Contributions
+
Questions, comments, and patches can always be sent to my public inbox, but I'm
also in my IRC channel/XMPP room pretty much 24/7. However, I might not see
messages right away because I'm working on something else (or sleeping) so
@@ -147,18 +165,15 @@ you like!
- IRC: [irc.nixnet.services/#secluded][irc]
- XMPP: [secluded@muc.secluded.site][xmpp]
-*If you haven't used mailing lists before, please take a look at [SourceHut's
+_If you haven't used mailing lists before, please take a look at [SourceHut's
documentation](https://man.sr.ht/lists.sr.ht/), especially the etiquette
-section.*
+section._
[reuse]: https://api.reuse.software/info/git.sr.ht/~amolith/earl
[reuse-shield]: https://shields.io/reuse/compliance/git.sr.ht/~amolith/earl
-
[fosspay]: https://secluded.site/donate/
[fosspay-shield]: https://shields.io/badge/donate-fosspay-yellow
-
-[wakapi-shield]: https://img.shields.io/endpoint?url=https://waka.secluded.site/api/compat/shields/v1/amolith/interval:any/project:umu&color=blue&label=time%20spent
-
+[wakapi-shield]: https://img.shields.io/endpoint?url=https://waka.secluded.site/api/compat/shields/v1/amolith/interval:any/project:earl&color=blue&label=time%20spent
[email]: mailto:~amolith/public-inbox@lists.sr.ht
[irc]: irc://irc.nixnet.services/#secluded
[xmpp]: xmpp:secluded@muc.secluded.site?join