README.md

umu

[![REUSE status][reuse-shield]][reuse] [![Donate with fosspay][fosspay-shield]][fosspay] ![Time spent on project][wakapi-shield]

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)

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
  • 400 Bad Request: URL parameter is required
  • 406 Not Acceptable: A shortened URL with this name already exists if provided name already exists in the database
  • URL mapped to $NAME (200 OK)

/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) 
    {
  "6H1g": "https://git.sr.ht/~amolith/umu/tree/dev",
  "N3yg": "https://secluded.site/"
}

/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
  • 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 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
  • 400 Bad Request: oldName parameter is required
  • 400 Bad Request: name parameter is required
  • 400 Bad Request: URL parameter is required
  • 406 Not Acceptable: A shortened URL with this name already exists if provided name already exists in the database
  • $URL mapped to $NAME (200 OK)

/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
  • 400 Bad Request: name parameter is required
  • $URL has been deleted (200 OK)

But … why?

Good question. URL shorteners are (usually) terrible and useless. Except when used correctly :thinkingsmart:

I take a lot of hand-written notes on things and, having both a passion for and job in IT, my notes would be much more useful if they included links to the things I'm writing about. However, there's no way I'm going to hand-write a 50+ character URL.

That's where URL shorteners come in!

Most shortener services I've found that are both open source and self-hosted use something like 6-character-long paths for the link 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.

Six characters is fine but why write six characters when you could write four :D

Also, why deal with user management and a relational database when you're only going to have one user and a bunch of keys with values :D

I also had a case of the typical "programmer unsatisfied with the {language|tech stack|license|feature set|all of the above}, wants to make something better" problem. I'm not a big fan of Node, PHP is ok, Python is meh, big relational database is unnecessary, heavy frontend is unnecessary, complex backend is unnecessary, I don't care about link tracking, click counts, link referrers, geo-location of visitors, etc., etc., etc.

All this put together, I decided I would be best served by using this as an opportunity to learn more Go and write my own thing that does nothing more than what I want need :)