Техническое задание на разработку HTTP сервиса поддержки REST API запросов для работы со списком задач на день

[asmazovec]

Общие положения

Данное техническое задание определяет требования к разработке HTTP сервиса поддержки REST API запросов для работы со "списком задач на день".

Сервис будет предоставлять возможности для добавления, актуализации и удаления задач, а также для получения списка задач на различные периоды времени. Сервис будет предоставлять инструменты планирования задач - создание задач на будущую дату, просмотр задач на выбранный период.

Предметная область

Основные сущности

1. Задача - описание деятельности пользователя, запланированное к определенной дате. Состав полей:
   • название задачи (обязательно),
   • описание задачи (опционально),
   • дата задачи (обязательно).

Деловой регламент

1. Задача планируется на текущую либо грядущую дату.
2. Если не указано обратного, задача назначается на текущую дату.

Основные требования к системе

Формат передачи данных: JSON.

Методы REST API: GET, POST, DELETE.

Логирование: по уровням важности (DEBUG, WARN, INFO).

Аутентификация и авторизация: JWT от Single Sign-On (SSO) включенный в заголовки запросов cookie.

Операции над задачами

Добавление новой задачи

• Метод: POST.
• URL: /tasks.
• Тело запроса: структура данных, представляющая задачу. Пример:

{
	"title": "Задача 1",
	"description": "Описание задачи 1",
	"due_date": "2023-04-15"
}

• Тело ответа: структура данных, соответствующая созданной задаче. Пример:

{
        "id": "<task_id>",
	"title": "Задача 1",
	"description": "Описание задачи 1",
	"due_date": "2023-04-15"
}

Актуализация существующей задачи

• Метод: PUT.
• URL: /tasks/{task_id}.
• Тело запроса: структура данных, представляющая задачу. Пример:

{
	"title": "Обновленная задача 1",
	"description": "Новое описание задачи 1",
	"due_date": "2023-04-20"
}

• Тело ответа: структура данных, соответствующая обновленной задаче. Пример:

{
        "id": "<task_id>",
	"title": "Обновленная задача 1",
	"description": "Новое описание задачи 1",
	"due_date": "2023-04-20"
}

Удаление задачи

• Метод: DELETE.
• URL: /tasks/{task_id}.
• В теле запроса не требуется передавать какие-либо данные.

Получение списка задач

Получение списка задач на день

• Метод: GET.
• URL: /tasks?date={unix timestamp}.
• Тело ответа: список структур данных, представляющих задачу. Пример:

{
  "tasks": [
    {
      "id": 1,
      "title": "Задача 1",
      "description": "Описание задачи 1",
      "due_date": "2023-04-15"
    },
    {
      "id": 2,
      "title": "Задача 2",
      "description": "Описание задачи 2",
      "due_date": "2023-04-15"
    },
    ...
  ]
}

Получение списка задач на неделю

• Метод: GET.
• URL: /tasks?date={unix timestamp}&week=true.
  Параметр week указывает, что нужно получить задачи за всю неделю.
• Тело ответа: список структур данных, представляющих задачу. Пример:

{
  "tasks": [
    {
      "id": 1,
      "title": "Задача 1",
      "description": "Описание задачи 1",
      "due_date": "2023-04-15"
    },
    {
      "id": 2,
      "title": "Задача 2",
      "description": "Описание задачи 2",
      "due_date": "2023-04-16"
    },
    ...
  ]
}

Получение списка задач за период

• Метод: GET
• URL: /tasks?start_date={unix timestamp}&end_date={unix timestamp}.
  Параметры start_date и end_date определяют начальную и конечную даты периода соответственно.
• Тело ответа: список структур данных, представляющих задачу. Пример:

{
  "tasks": [
    {
      "id": 1,
      "title": "Задача 1",
      "description": "Описание задачи 1",
      "due_date": "2023-04-15"
    },
    {
      "id": 2,
      "title": "Задача 2",
      "description": "Описание задачи 2",
      "due_date": "2023-04-16"
    },
    ...
  ]
}

Обработка ошибок и логирование

Сервис будет оснащен системой обработки ошибок, которая предусматривает возврат соответствующих HTTP статус-кодов вместе с информативными сообщениями об ошибках. Это поможет клиентам API легче понять причины возникновения проблем и быстрее найти пути их решения.

Ошибки клиента

В случае возникновения ошибок на стороне клиента (например, неверно составленного запроса), сервис будет возвращать соответствующий HTTP статус-код в диапазоне 400-499. В теле ответа будет передан JSON-объект, содержащий информацию о типе ошибки и подробное описание проблемы. Пример:

{
	"message": "Неверный формат даты в параметре 'due_date'"
}

Все ошибки, возникшие в результате обработки запроса клиента сервиса, должны быть залогированы для последующего анализа с уровнем INFO.
Все успешные действия пользователя должны быть залогированы для последующего анализа и аудита с уровнем INFO.

Ошибки сервера

При возникновении ошибок на стороне сервера (например, проблемы с доступом к базе данных), сервис будет возвращать HTTP статус-код в диапазоне 500-599. В теле ответа будет передан JSON-объект, содержащий информацию о типе ошибки. Детали проблемы на стороне сервера клиентам передаваться не будут, чтобы избежать возможных угроз безопасности. Пример:

{
	"message": "Произошла ошибка на стороне сервера. Пожалуйста, попробуйте еще раз позже."
}

Все ошибки, возникающие на стороне сервера, должны быть залогированы для последующего анализа и устранения проблем с уровнем WARN.

Производительность и безопасность

Требования к производительности:

• Время ответа на запрос не должно превышать 200 мс.

Требования к безопасности:

• Все данные, передаваемые между клиентом и сервером, должны быть зашифрованы.
• Сервис должен быть защищен от основных векторов атак, таких как SQL-инъекции, XSS и CSRF атаки.