Add API docs

Amolith created

Change summary

README.md        | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++
updateHandler.go |  4 +-
2 files changed, 83 insertions(+), 2 deletions(-)

Detailed changes

README.md 🔗 

@@ -14,6 +14,87 @@ Service has …
 - 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)  
+  ``` json
+  {
+    "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:

updateHandler.go 🔗 

@@ -43,7 +43,7 @@ func (m *model) updateHandler(writer http.ResponseWriter, request *http.Request)
 		}
 	}
 
-	m.update(name, destination, oldName)
+	response := m.update(name, destination, oldName)
 
-	http.Error(writer, fmt.Sprint("\"", name, "\" mapped to \"", destination, "\""), 200)
+	writer.Write([]byte(response))
 }