Мини-сервис сокращения ссылок

локальный запуск

1. клонировать репозиторий

git clone git@github.com:boundlessend/shorto.git
cd shorto

2. создать и активировать виртуальное окружение

macOS / linux:

python3 -m venv venv
source venv/bin/activate

win powershell:

python -m venv venv
.\venv\Scripts\Activate.ps1

3. установить зависимости

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

4. запустить приложение

uvicorn app.main:app --reload

после старта сервис будет тут:

• API: http://127.0.0.1:8000
• Swagger UI: http://127.0.0.1:8000/docs

---

как запустить тесты

pytest .

---

API

1. создаем короткую ссылку

POST/links

пример тела запроса:

{
"original_url": "https://example.com/very/long/path",
"custom_code": "my-link",
"expires_in_seconds": 3600
}

поля:

• original_url — обязательный URL;
• custom_code — опциональный кастомный код;
• expires_in_seconds — опциональный TTL в секундах.

пример успешного ответа:

{
"original_url": "https://example.com/very/long/path",
"code": "my-link",
"short_url": "http://127.0.0.1:8000/my-link",
"created_at": "2026-03-25T10:00:00Z",
"expires_at": "2026-03-25T11:00:00Z",
"is_active": true
}

2. переходим по короткому коду

GET/{code}

• если ссылка существует и активна — происходит редирект;
• если ссылка не найдена — 404;
• если срок жизни истек — 410;
• если ссылка деактивирована — 410.

3. получаем статистиек по ссылке

GET/links/{code}

пример ответа:

{
"original_url": "https://example.com/very/long/path",
"code": "my-link",
"created_at": "2026-03-25T10:00:00Z",
"expires_at": "2026-03-25T11:00:00Z",
"clicks": 3,
"is_active": true,
"is_deleted": false
}

4. деактивируем ссылку

DELETE/links/{code}

пример ответа:

{
"message": "Ссылку деактивировали, всё ок.",
"code": "my-link",
"is_active": false
}

5. получаем список всех ссылок

GET/links

возвращает массив всех ссылок с базовой информацией.

---

формат ошибок

ответ ошибки приходит единообразно:

{
"error": {
"code": "validation_error",
"message": "Request validation failed.",
"details": [
{
"type": "url_parsing",
"loc": ["body", "original_url"],
"msg": "Input should be a valid URL"
}
]
}
}

примеры кодов ошибок:

• validation_error
• custom_code_already_exists
• link_not_found
• link_expired
• link_inactive

---

сценарии ручной проверки

1. создаем ссылку с автогенерацией кода

curl -X POST "http://127.0.0.1:8000/links" \
-H "Content-Type: application/json" \
-d '{ "original_url": "https://example.com/long/path" }'

2. создаем ссылку с кастомным кодом

curl -X POST "http://127.0.0.1:8000/links" \
-H "Content-Type: application/json" \
-d '{ "original_url": "https://example.com/custom", "custom_code": "my-custom-code" }'

3. создаем ссылку со сроком жизни

curl -X POST "http://127.0.0.1:8000/links" \
-H "Content-Type: application/json" \
-d '{ "original_url": "https://example.com/temp", "expires_in_seconds": 60 }'

4. получаем статистику по ссылке

curl "http://127.0.0.1:8000/links/my-custom-code"

5. переходим по короткой ссылке

curl -i "http://127.0.0.1:8000/my-custom-code"

6. пробуем создать ссылку с занятым custom_code

curl -X POST "http://127.0.0.1:8000/links" \
-H "Content-Type: application/json" \
-d '{ "original_url": "https://example.com/another", "custom_code": "my-custom-code" }'

ожидается 409 Conflict.

7. деактивируем ссылку и чекаем, что редирект больше не работает

curl -X DELETE "http://127.0.0.1:8000/links/my-custom-code"
curl -i "http://127.0.0.1:8000/my-custom-code"

после деактивации ожидается 410 Gone.

---

что некст делаем

1. мб постоянное хранилище (PostgreSQL / Redis).
2. добавляем rate limiting
3. хз, добавить удаление просроченных ссылок фоном
4. добавить owner/user и авторизацию
5. добавить более гибкий фильтр и пагинацию для списка ссылок
6. Добавить конфигурацию через .env
7. Добавить логирование и middleware для request-id