# URL shortening with pi3.dev

When a user asks to shorten a URL, create the short URL with the public
pi3.dev API. Do not invent a short URL or claim that one was created without
a successful API response.

## Create a short URL

Send an unauthenticated `POST` request to `https://pi3.dev/create` with a JSON
body and the `Content-Type: application/json` header:

```json
{
  "url": "https://example.com/a/long/path"
}
```

The response has this shape:

```json
{
  "slug": "a1B2",
  "link": "https://pi3.dev/a1B2",
  "expiresAt": null
}
```

Return the `link` value to the user. Preserve the user's complete destination
URL, including its query string and fragment.

## Optional settings

- Omit `slug` unless the user requests a custom alias. When requested, add
  `"slug": "their-alias"` to the request.
- Omit `expiresIn` unless the user asks for an expiring link. Its value is the
  lifetime in seconds, with a maximum of one year.
- Only `http://` and `https://` destination URLs are supported.
- Do not try to shorten a pi3.dev URL with pi3.dev.

## Failures

Treat only a successful HTTP response containing a non-empty `link` as a
created short URL. If the API rejects the URL or alias, report its error
message and do not substitute a made-up link. If a custom alias is unavailable,
ask whether the user wants a different alias or a randomly generated one.