reversemind

Практика: проектирование REST API для сервиса типа Яндекс.Такси

· 1 мин чтения

#api#rest#практика#system design#бэкенд

Краткое описание подхода к проектированию REST API для сервиса, аналогичного Яндекс.Такси: от простых методов к сложным, с учётом RESTful-структуры и выбора HTTP-методов.

Подход

  • Начинать с простых методов (профили), затем добавлять расчёты, заказы и события.
  • Использовать ресурсы и подресурсы: /drivers, /passengers, /orders, /passengers/{id}/history.
  • Параметры пути — для идентификаторов, query-параметры — для фильтров.

Эндпоинты (базовый набор)

1. Профиль водителя

  • GET /drivers/{driver_id}
  • Ответ: driver_id, name, phone_number, rating, car (модель, цвет, номер).

2. Профиль пассажира

  • GET /passengers/{passenger_id}
  • Ответ: passenger_id, name, phone_number, rating.

3. История поездок пассажира

  • GET /passengers/{passenger_id}/history
  • Ответ: массив поездок с ride_id, date, details (from, to, cost, route). Для больших списков — пагинация (?page=1&limit=10).

4. Расчёт стоимости и времени

  • GET /rides/estimations?from=...&to=...
  • Ответ: estimation_id, cost, duration (секунды). estimation_id используется при заказе, чтобы не пересчитывать.

5. Заказ такси

  • POST /orders
  • Тело: estimation_id (опционально), from, to.
  • Ответ: ride_id, данные водителя (driver_id, name, phone_number), status: "confirmed".

6. Отмена заказа

  • DELETE /orders/{ride_id}
  • Ответ: 204 No Content. В реальной системе часто делают логическое удаление (флаг cancelled) и при необходимости PATCH для смены статуса.

7. События поездки

  • GET /events/{ride_id}
  • Ответ: ride_id, массив events с полями type (driver_arrived, passenger_entered, position_changed, route_changed), timestamp, details. Клиент может опрашивать эндпоинт; альтернатива — WebSocket для стрима событий.

Нюансы

  • HTTP-методы: GET — чтение, POST — создание заказа, DELETE — отмена (или PATCH для статуса).
  • Хранение: estimation_id на клиенте для повторного использования при заказе; история отменённых заказов — на сервере (логическое удаление).
  • Версионирование: в проде часто вводят префикс версии, например /v1/drivers.
  • Ошибки: в реальном API нужны коды (404 для несуществующего driver_id, 4xx/5xx с телом ошибки).

Такой набор покрывает базовый сценарий: просмотр профилей, историю, расчёт, заказ, отмену и отслеживание статуса поездки через события.