1# umu
  2Personal shortlink generator
  3
  4## Features
  5Links are …
  6- Editable
  7- Removable
  8- Four characters long (26 uppercase letters + 26 lowercase letters + 10 numbers
  9  = 14,776,336 possible shortened URLs)
 10
 11Service has …
 12- A simple API
 13- A simple web UI
 14- A simple backup procedure (database is a single directory)
 15- No user management (this is a *personal* service after all)
 16
 17## API documentation
 18
 19### `/create`
 20
 21#### Required parameters
 22- `url`: percent-encoded URL being shortened
 23
 24#### Optional parameters
 25- `name`: percent-encoded short link the `url` will be mapped to. If this is not
 26  provided, a random, 4-character code will be generated instead.
 27
 28#### Output
 29- `401 Unauthorized: You do not have permission to create shortlinks` if access
 30  token provided in `Authorization` header does not match the configured access
 31  token
 32- `400 Bad Request: URL parameter is required`
 33- `406 Not Acceptable: A shortened URL with this name already exists` if
 34  provided name already exists in the database
 35- `URL mapped to $NAME` (200 OK)
 36
 37### `/read`
 38
 39#### Required parameters
 40- None
 41
 42#### Optional parameters
 43- None
 44
 45#### Output
 46- `401 Unauthorized: You do not have permission to view shortlinks` if access
 47  token provided in `Authorization` header does not match the configured access
 48  token
 49- JSON representation of the key/value database (200 OK)  
 50  ``` json
 51  {
 52    "6H1g": "https://git.sr.ht/~amolith/umu/tree/dev",
 53    "N3yg": "https://secluded.site/"
 54  }
 55  ```
 56
 57### `/update`
 58
 59#### Required parameters:
 60- `oldName`: percent-encoded name the URL is *currently* referred to with
 61- `name`: percent-encoded name the URL *will* be referred to with
 62- `url`: percent-encoded URL being shortened
 63
 64`name` and `url` are first set as a key/value pair. If `name` already exists,
 65`url` is updated. If `name` does *not* already exist, it's created and `oldName`
 66is deleted. If the user is only modifying `url`, `oldName` and `name` should
 67both be submitted but their values should be identical.
 68
 69#### Optional parameters:
 70- None
 71
 72#### Output:
 73- `401 Unauthorized: You do not have permission to create shortlinks` if access
 74  token provided in `Authorization` header does not match the configured access
 75  token
 76- `400 Bad Request: oldName parameter is required`
 77- `400 Bad Request: name parameter is required`
 78- `400 Bad Request: URL parameter is required`
 79- `406 Not Acceptable: A shortened URL with this name already exists` if
 80  provided name already exists in the database
 81- `$URL mapped to $NAME` (200 OK)
 82
 83### `/delete`
 84
 85#### Required parameters:
 86- `name`: percent-encoded short link
 87
 88#### Optional parameters:
 89- None
 90
 91#### Output:
 92- `401 Unauthorized: You do not have permission to create shortlinks` if access
 93  token provided in `Authorization` header does not match the configured access
 94  token
 95- `400 Bad Request: name parameter is required`
 96- `$URL has been deleted` (200 OK)
 97
 98## But … why?
 99Good question. URL shorteners are (usually) terrible and useless. Except when
100used correctly :thinkingsmart:
101
102I take a lot of hand-written notes on things and, having both a passion for and
103job in IT, my notes would be much more useful if they included links to the
104things I'm writing about. However, there's no way I'm going to hand-write a 50+
105character URL.
106
107That's where URL shorteners come in!
108
109Most shortener services I've found that are both open source and self-hosted use
110something like 6-character-long paths for the link as they're meant for use by
111multiple people; 14.8m possible URLs (your cap with 4 character paths) aren't
112enough for public services.
113
114Six characters is *fine* but why write six characters when you could write four :D
115
116Also, why deal with user management and a relational database when you're only
117going to have one user and a bunch of keys with values :D
118
119I also had a case of the typical "programmer unsatisfied with the {language|tech
120stack|license|feature set|all of the above}, wants to make something better"
121problem. I'm not a big fan of Node, PHP is ok, Python is meh, big relational
122database is unnecessary, heavy frontend is unnecessary, complex backend is
123unnecessary, I don't care about link tracking, click counts, link referrers,
124geo-location of visitors, etc., etc., etc.
125
126All this put together, I decided I would be best served by using this as an
127opportunity to learn more Go and write my own thing that does nothing more than
128what I want need :)