diff --git a/README.md b/README.md index 6e117a38e2a5478225808583d0c0c831c83eab2b..3c81249908fa29e5732cf08ccf8fc2703d9aedea 100644 --- a/README.md +++ b/README.md @@ -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