Ниже я постарался описать первую версию протокола для запроса имеющихся карт у магазина. В будущем планируется усовершенствовать этот алгоритм для детального поиска, например только альтернативные версии карт или только фойл, но лучше начинать с маленьких шагов, а дальше уже оптимизировать. Так же более интересный механизм работы.
Это не конечная реализация, а та к которой стоит стремится. Каждая реализация может отличатся особенностью каждого магазина. Мы не можем на неё повлиять. Каждый пункт обсуждаем и будет адаптироваться.
Весь процесс можно коротко описать как GET запрос на сервер магазина с указанием карты и в ответ он хочет получить JSON документ с ссылками на карточки с информацией. Но теперь погрузимся в детали.
Пользователь вводит на сайте название карты, сайт помогает ему найти правильное название карты, сверяясь с базой карт. Результат данной части процесса — правильное название карты на английском языке.
Например, пользователь искал карту с названием удар молнии. Результат будет Lightning Bolt.
Сайт берёт название карты Lightning Bolt и делает GET запрос к магазину с этим названием. Запрос может быть как с авторизацией, так и без неё. По желанию. Название карты будет закодировано в get параметрах. Иногда их называют search параметрами.
В ответе ожидается массив из объектов карт. Каждый объект содержит в себе название, количество, цену, состояние, язык, код издания, флаг фойл, реферальные параметры или ссылка.
Время ожидания запроса 4 секунды. За это время ожидается, что ответ будет сформирован. Иначе будет считаться, что магазин в данным момент недоступен.
Запросы не будут кэшироваться во избежании неправильной выдачи результатов и всегда актуальной выдачи пользователю.
Пример адреса с GET запросом — https://awesome-magic-shop.co/api/v1/search?name=Lightning%20Bolt
Пример документа JSON из ответа:
[
{
"name": "Lightning Bolt",
"lang": "en",
"uri": "https://awesome-magic-shop.co/cards/sta/42-en-nm-foil?utm_source=pauper.ru",
"foil": true,
"condition": "NM",
"set": "sta",
"collector_number": "42",
"price": 1250
},
{
"name": "Lightning Bolt",
"lang": "ru",
"uri": "https://awesome-magic-shop.co/cards/sta/42-ru-nm?utm_source=pauper.ru",
"foil": false,
"condition": "NM",
"set": "sta",
"collector_number": "42",
"price": 250
}
]Результат данной части — JSON документ, который возвращается в ответе.
Альтернативным вариантом может быть передача параметров запроса через body. В этом случае будет сформирован JSON, и отправлен как body внутри POST запроса. Результат подразумевается такой же. Плюсы альтернативного варианта в том, что можно искать сразу несколько карт списком.
Сайт обработает полученные JSON, сортирует и выводит список найденых результатов.
Пользователь видит актуальные данные, выбирает понравившуюся карту и переходит по ссылке в магазин.