Func

README.md

@@ -48,13 +48,15 @@ All paths are relative to the server URL. `{id}` is a path parameter containing
 | --- | --- | --- | --- | --- |
 | `content` | String | Yes | — | Text or code to store. For raw text requests, the entire body supplies this value. |
 | `language` | String | No | Not set | Language for syntax highlighting. |
-| `expires` | Integer | No | No expiration | Expiration time in seconds |
-| `max_views` | Integer | No | Unlimited views | Maximum number of views before self-destruction. The `/once` routes force this to `1`. |
+| `expires` | Integer | No | No expiration | Lifetime in seconds from the request; `0` expires immediately. Must be nonnegative. |
+| `max_views` | Integer | No | Unlimited views | Positive maximum number of views before self-destruction. The `/once` routes force this to `1`. |
 
 **Authentication:** optional HTTP Basic authentication. If supplied, the paste is associated with that user. An account is created if the user does not exist.
 
 **Returns:** the assigned ID as plain text. This is an ID, not a full URL. Always use the returned ID, since a requested custom ID may already be taken.
 
+IDs are shared by pastes and short links. Reserved route names (`list`, `once`, `to`, and `static`) and IDs containing `/` are unavailable as custom IDs; these also receive a generated ID.
+
 Create a paste from raw text:
 
 ```sh
@@ -89,7 +91,9 @@ curl --request POST 'http://localhost:3000/once/my-secret' \
 | `id` | Path | Yes | The paste ID returned when it was created. |
 | `Accept` | Header | No | Use `text/html` for syntax-highlighted HTML or `text/plain` for plain text. |
 
-**Returns:** the paste as HTML or plain text, based on the `Accept` header. The default representation is not defined yet.
+**Returns:** the paste as HTML or plain text, based on the `Accept` header. The default is plain text. HTML uses the stored language for syntax highlighting, falling back to plain text for missing or unknown languages.
+
+Each successful read increments `views`. The final permitted read returns the content and deletes the paste. Missing, expired, and exhausted pastes return `404`. Expired and exhausted records are also cleaned up in the background every minute.
 
 ```sh
 curl 'http://localhost:3000/my-paste' \
@@ -103,24 +107,28 @@ curl 'http://localhost:3000/my-paste' \
 | `POST` | `/to` | Create a short link with a generated ID. |
 | `POST` | `/to/{id}` | Use the requested ID if available; otherwise generate a random ID. |
 
-**Request body:** the destination URL as raw text, or an `application/x-www-form-urlencoded` form with the following parameter:
+**Request body:** the destination URL as raw text, or an `application/x-www-form-urlencoded` form with the following parameters:
 
 | Form parameter | Type | Required | Description |
 | --- | --- | --- | --- |
-| `href` | String | Yes | Destination URL. For raw text requests, the entire body supplies this value. |
+| `href` | String | Yes | Absolute HTTP or HTTPS destination URL. For raw text requests, the entire body supplies this value. |
+| `expires` | Integer | No | Lifetime in seconds from the request; `0` expires immediately. Must be nonnegative. Defaults to no expiration. |
+| `max_views` | Integer | No | Positive maximum number of redirects before self-destruction. Defaults to unlimited redirects. |
 
 **Returns:** the assigned ID as plain text. Use it in `/to/{id}` to follow the link.
 
 ```sh
 curl 'http://localhost:3000/to' \
-  --data-urlencode 'href=https://example.com'
+  --data-urlencode 'href=https://example.com' \
+  --data-urlencode 'expires=3600' \
+  --data-urlencode 'max_views=5'
 ```
 
 ### Follow a short link
 
 `GET /to/{id}` looks up a short link by its ID.
 
-**Returns:** an HTTP redirect to the destination URL when found. The redirect status code and behavior for missing links are not defined yet.
+**Returns:** a `307 Temporary Redirect` to the destination URL, or `404` if the link is missing, expired, or exhausted. Each successful redirect increments `views`. The final permitted redirect deletes the short link immediately. Expiration and view limits use the same logic as text pastes.
 
 ### Update a paste
 
@@ -128,21 +136,44 @@ curl 'http://localhost:3000/to' \
 
 **Authentication:** HTTP Basic authentication of the creator is required.
 
-The same request body as [the POST request](#create-a-paste)
+The same request body as [the POST request](#create-a-paste). `content` is required; omitted `language`, `expires`, and `max_views` retain their current values. A supplied `expires` starts a new lifetime from the update request. The view counter is preserved, and `updated_at` is set to the current time.
 
-### Delete a paste
+**Returns:** `204 No Content` on success, `401` without authentication, `403` for another user's paste or an anonymous paste, and `404` for a missing, expired, or exhausted paste.
 
-`DELETE` delete a paste by its ID.
+### Update a short link
+
+`PUT /to/{id}` updates a short link by its ID.
 
 **Authentication:** HTTP Basic authentication of the creator is required.
 
+Use the same request body as [creating a short link](#create-a-short-link): the new destination as raw text, or a form with `href` and optional `expires` and `max_views`. Omitted options retain their current values. The view counter is preserved, and `updated_at` is set to the current time.
+
+**Returns:** `204 No Content` on success, with the same authentication and missing-record errors as the paste update endpoint. Invalid destination URLs return `400`.
+
+```sh
+curl --request PUT --user 'alice:example-password' 'http://localhost:3000/to/my-link' \
+  --data-urlencode 'href=https://example.org' \
+  --data-urlencode 'expires=3600' \
+  --data-urlencode 'max_views=10'
+```
+
+### Delete a paste
+
+`DELETE /{id}` deletes a paste or short link by its ID.
+
+**Authentication:** HTTP Basic authentication of the creator is required.
+
+**Returns:** `204 No Content` on success, with the same authentication and missing-paste errors as the update endpoint.
+
 ### List pastes
 
-`GET /list` returns a list of notes.
+`GET /list` returns the authenticated user's pastes and short links.
 
 **Authentication:** HTTP Basic authentication is required.
 
-**Returns:** a plain-text list of the notes that are present and their content.
+**Returns:** a plain-text list of that user's active records, ordered by creation time and ID. Each entry contains the ID on one line, followed by the content, with a blank line between entries. An empty list returns an empty body. Listing does not increment view counters. Missing authentication returns `401`.
+
+With `Accept: text/html`, the response is an HTML table containing IDs, types, content, languages, view counts and limits, creation and update times, and expiration times. Dates are displayed in the browser's local timezone.
 
 ```sh
 curl --user 'alice:example-password' 'http://localhost:3000/list'