81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
# API reference
|
|
|
|
All paths are relative to the path in `base_url`. Every frontend, API,
|
|
metadata, deletion, and short-code route accepts trailing slashes, including
|
|
when a query string follows the slash.
|
|
|
|
## Health and frontend
|
|
|
|
- `GET /` serves the embedded frontend when `production=false`.
|
|
- `GET /api/health` returns HTTP 200:
|
|
|
|
```json
|
|
{"status": "ok", "service": "url-shortener"}
|
|
```
|
|
|
|
With a non-empty base path, requesting the bare path redirects to its trailing
|
|
slash form; for example, `/s` redirects to `/s/`.
|
|
|
|
## Create a short URL
|
|
|
|
`POST /api/shorten` and `GET /api/shorten` are supported without an API key.
|
|
Fields may be supplied as query parameters or in a JSON body; query parameters
|
|
take precedence.
|
|
|
|
| Field | Required | Description |
|
|
|---|---:|---|
|
|
| `url` | yes | Absolute `http://` or `https://` URL. |
|
|
| `retention_days` | no | Per-URL lifetime, or zero to keep forever. |
|
|
|
|
Success is HTTP 201 with only the short URL as UTF-8 plain text:
|
|
|
|
```text
|
|
https://example.com/s/aB3xYz
|
|
```
|
|
|
|
Codes begin at `min_short_length`. After ten collisions at one length, ushort
|
|
tries the next length through `max_short_length`.
|
|
|
|
## List URLs
|
|
|
|
`GET /api/urls?api_key=<key>` returns all rows newest first. A missing or
|
|
invalid key returns HTTP 403 with an empty body.
|
|
|
|
```json
|
|
{
|
|
"count": 1,
|
|
"urls": [
|
|
{
|
|
"short_code": "aB3xYz",
|
|
"short_url": "https://example.com/s/aB3xYz",
|
|
"original_url": "https://example.org",
|
|
"created_at": 1710000000,
|
|
"visit_count": 5,
|
|
"retention_days": 30
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Metadata and lookup
|
|
|
|
- `GET /api/urls/<code>` returns one metadata object without authentication.
|
|
- `GET /api/lookup?url=<encoded-url>` returns the newest matching metadata
|
|
object without authentication.
|
|
- A missing record returns HTTP 404 with an empty body.
|
|
|
|
## Delete
|
|
|
|
`DELETE /api/urls/<code>?api_key=<key>` returns:
|
|
|
|
- HTTP 204 with an empty body on success;
|
|
- HTTP 404 with an empty body when the code does not exist; or
|
|
- HTTP 403 with an empty body when authentication fails.
|
|
|
|
## Redirect
|
|
|
|
`GET /<code>` atomically increments `visit_count` and responds with HTTP 302 to
|
|
the stored original URL.
|
|
|
|
Every response includes the compatibility CORS and security headers.
|