commit - 71bdede3e2286e895508fbbfe745eef880db6b7b
commit + 4676ea2acb5a1129ec3c28ba660b60f19e2869ec
blob - 70a96baa3e7659165e272377c67571412f35e57e
blob + 26ca606503577fc68724b9691e1a068512b79e04
--- .build.yml
+++ .build.yml
@@ -1,7 +1,14 @@
 image: openbsd/latest
 packages:
   - go
+  - node
+  - ruby-2.7.5
 sources:
   - https://git.sr.ht/~otl/mailmux
 tasks:
   - test: cd mailmux && go test ./...
+  - docs: |
+      cp mailmux/docs/httpapiref.md slate/source/index.html.md
+      gem install bundler
+      bundle install
+      bundle exec middleman build
blob - /dev/null
blob + 5af8e3e5a81c2cd5ecd88534cf731e7c5465055b (mode 644)
--- /dev/null
+++ docs/httpapiref.md
@@ -0,0 +1,209 @@
+---
+title: API Reference
+
+language_tabs:
+  - shell
+
+---
+
+# Introduction
+
+The API is based on a REST API, similar to the one provided by [Stripe].
+Some requests can contain parameters, which should be URL-encoded forms in the request body.
+Responses are JSON-encoded.
+
+[stripe]: https://stripe.com/docs/api
+
+# Authentication
+
+Authentication to the API is performed via [HTTP Basic Authentication][basicauth].
+
+[basicauth]: https://datatracker.ietf.org/doc/html/rfc7617
+
+# Errors
+
+```json
+{
+  "error": "lookup wonders_underbelly71: no such alias"
+}
+```
+
+Responses to HTTP API requests include conventional HTTP status codes.
+Briefly: codes beginning with 2 indicate success.
+Codes beginning with 4 indicate some error with the client request.
+Codes beginning with 5 indicate an error with the servers.
+
+In almost all cases, a JSON object with one key, `error`, is returned whose value
+contains a description of what went wrong.
+
+# Registration
+
+```
+POST /v1/register
+```
+
+```shell
+curl -u 'test@example.com:mysecret' https://mailmux.example.net/v1/aliases
+```
+
+Registration creates an account with the service.
+The username must be a valid email address.
+The username and password can be used for further API requests.
+
+## Parameters
+
+<dl>
+<dt><code>username</code> string</dt>
+<dd>A full email address.</dd>
+<dt><code>password</code> string</dt>
+<dd>A password with preferably at least 12 characters.</dd>
+</dl>
+
+# Aliases
+
+```
+POST   /v1/aliases
+GET    /v1/aliases
+GET    /v1/aliases/:recipient
+POST   /v1/aliases/:recipient
+DELETE /v1/aliases/:recipient
+```
+
+An Alias is used to route mail.
+Any mail addressed to the recipient of the alias will be forwarded to its destination.
+
+## Alias object
+
+```json
+{
+  "Recipient": "wondering_underbelly71",
+  "Destination": "test@example.com",
+  "Expiry": 1845067777,
+  "Note": "newsletters for example.org"
+}
+```
+
+An Alias has the following fields:
+
+<dl>
+<dt><code>Recipient</code> string</dt>
+<dd>Just the username part of a publicly visible email address.
+The domain(s) available for accepting mail depend on the SMTP server
+implementation.</dd>
+<dt><code>Destination</code> string</dt>
+<dd>Destination contains an email address, with domain suffix,
+to which mail will be forwarded.</dd>
+<dt><code>Expiry</code> integer</dt>
+<dd>Expiry specifies a time in seconds since the UNIX epoch
+after which the alias is considered inactive;
+that is, mail addressed to Recipient should be bounced.</dd>
+<dt><code>Note</code> string</dt>
+<dd>Note contains user-defined text that can be used to, for example, identify the alias.</dd>
+</dl>
+
+
+## Create an alias
+
+```
+POST /v1/aliases
+```
+
+```json
+{
+  "Recipient": "wondering_underbelly71",
+  "Destination": "test@example.com",
+  "Expiry": 1845067777,
+  "Note": "newsletters for example.org"
+}
+```
+
+Creates an alias with recipient set to a unique randomly generated username.
+If successful, the new alias object is returned.
+Otherwise, an error is returned.
+
+### Parameters
+
+<dl>
+<dt><code>Expiry</code> optional integer</dt>
+<dd>Expiry specifies a time in seconds since the UNIX epoch
+after which the alias is considered inactive;
+that is, mail addressed to Recipient should be bounced.
+By default, aliases never expire.</dd>
+<dt><code>Note</code> optional string</dt>
+<dd>Note contains user-defined text that can be used to, for example, identify the alias.
+By default, aliases have no note.</dd>
+</dl>
+
+## Retrieve an alias
+
+```
+GET /v1/aliases/:recipient
+```
+
+```json
+{
+  "Recipient": "wondering_underbelly71",
+  "Destination": "test@example.com",
+  "Expiry": 1845067777,
+  "Note": "newsletters for example.org"
+}
+```
+
+Retrieves the alias with the named recipient, if any.
+
+### Parameters
+
+None.
+
+## List aliases
+
+```
+GET /v1/aliases
+```
+
+```json
+[
+  {
+    "Recipient": "wondering_underbelly71",
+    "Destination": "test@example.com",
+    "Expiry": 1845067777,
+    "Note": "newsletters for example.org"
+  },
+  {
+    "Recipient": "humble_anteater48",
+    "Destination": "test@example.com",
+    "Expiry": 1845067777,
+    "Note": "supermarket rewards card"
+  }
+]
+```
+
+Returns all aliases for the current user.
+
+#### Parameters
+
+None.
+
+## Update an alias
+
+```
+POST /v1/aliases/:recipient
+```
+
+This is used to modify the named alias.
+
+### Parameters
+
+To unset parameters, set their values to the empty string (`""`).
+This can be used to, for example, remove an alias' expiry time.
+
+<dl>
+<dt><code>Expiry</code> optional integer</dt>
+<dd>Expiry specifies a time in seconds since the UNIX epoch
+after which the alias is considered inactive;
+that is, mail addressed to Recipient should be bounced.
+By default, aliases never expire.</dd>
+<dt><code>Note</code> optional string</dt>
+<dd>Note contains user-defined text that can be used to, for example, identify the alias.
+By default, aliases have no note.</dd>
+</dl>