Get Started. It's Free
or sign up with your email address
Rocket clouds
apiv2 by Mind Map: apiv2

1. даты у нас бывают двух типов: 1) абстрактная дата (день рождения) 2) конкретный момент во времени (время совершения транзакции) Хотелось бы их различать на уровне типов.

1.1. в чем разница?

1.1.1. день рождения нельзя хранить в виде таймстампа (это некая абстрактная цифра, а не момент во времени)

1.1.1.1. отдельный тип

1.2. день рождения может быть строкой

1.2.1. В принципе да, но обычно он связан с возрастом, так что логичнее сделать спец тип.

1.2.1.1. +1

2. автоматическая сериализация\десериализация ответов и запросов в json, xml без доработок для каждого метода

2.1. маппинг в доменную модель фронта все равно придется где-то прописать

3. мультитранспортность

3.1. вебсокеты

3.2. rest

3.2.1. именно REST, или все-таки HTTP?

3.3. логично сделать абстрактный транспорт, для которого написать различные имплементации

3.3.1. ... или не писать и просто взять акковский стрим

3.3.1.1. при чем тут акковский стрим и абстрактный транспорт?

3.3.1.1.1. при том, что это готовая абстракция высокого уровня, предусматривающая разные бэкэнды для маршаллизации. какую задачу решит наш собственный абстрактный транспорт? даст гипотетическую возможность перескочить с json на protobuff?

3.3.2. Надо доработать хендлер разбив логику на две части: конвертация запроса в кейз-класс с параметрами и собственно работа с кейз классом. Подразумевается что кейзклас полностью определяет ограничения на параметры запроса, в тч формат, обязательность и т.п.

3.3.2.1. "Конвертацию запроса" я называю маппингом из доменной модели фронта в нашу доменную модель. Собственно +1.

3.3.2.2. да, это было бы круто, но как быть с хендлерами, принимающими несколько наборов параметров?

3.3.2.2.1. надо понимать, что отдельный набор параметров это отдельная точка входа - отдельный case class. Вот и все.

3.3.3. Конвертор можно делать как автоматическим (рефлекшн, макросы и т.п) так и нет.

3.3.3.1. рефлекшн - это построение конвертора в рантайме -> тормоза. можно их кэшировать, конечно, но проще сразу взять макросы.

3.3.3.1.1. по умолчанию имплиситный макрос, имплисит можно перекрыть эксплиситом в случае, когда дефолтная десериализация не спасает

3.3.4. Тогда можно часть хендлеров вызывать через веб-сокеты. В принципе если хедлер к такому преобразован - дальше все просто.

3.3.4.1. Логично - если хендлер подготовлен.

3.4. HTTP/2

3.4.1. как только выйдем обновим nginx

3.5. Streaming API a la Twitter - проще, чем websocket

3.5.1. Play Iteratees?

3.5.2. О чем вы вообще говорите - websockets это просто транспорт. WiFi еще круче.

3.5.2.1. ВебСокеты - это как раз-таки протокол. И их реализация достаточно тяжеловесна. Стримы а-ля Твиттер - это по сути незакрывающиеся сокеты с потоком json-объектов, что позволяет гораздо проще переиспользовать JSON-десериализаторы, например.

3.5.2.1.1. хорошо, websocket'ы - это протокол транспортного уровня. Давайте уже отделим транспортный уровень от уровня приложения.

3.5.2.2. Плюс к тому, в стандартах на вебсокеты постоянно ломается обратная совместимость.

3.5.2.2.1. устаревшая информация

3.6. ИТОГО

3.6.1. по вебсокетам делаем и реквест и респонс

3.6.1.1. data оборачиваем в envelop

3.6.1.2. выяснить про безопасность. Овечкин

3.6.1.3. клиент всегда передает requestId, который прлетает еще и в ответе

3.6.1.4. 2 типа ответа Response и Event

3.6.2. берем xml и json

3.6.2.1. для ответов всегда отдельный тип данных Response*

3.6.3. метод для лонгполинга событий если сокеты сдохли

3.6.4. транспорты

3.6.4.1. rest http

3.6.4.1.1. best practive по именован от Овечкина

3.6.4.2. вебсокеты

3.6.5. только сессия в параметрах

3.6.6. v2/object/do/?sessionId=

3.6.6.1. все остальные параметры постом

3.6.6.1.1. отдельные методы можно будет специально разрешать пользовать гетом

3.6.7. Кузьмин говорит, что для них реквесты через сокеты ок

3.6.8. всегда возвращаем 200

4. стандартизация асинхронных событий на фронт

5. правила именования в протоколе

5.1. Использовать единую нотацию для именования полей JSON, чтобы больше не было подобных вещей как два sessionid и sessionId при логине. Пусть везде будет либо camelCase либо underscore_notation

5.2. итого

5.2.1. для сервисов

5.2.2. для доменной модели

5.2.3. для полей запроса ответа

6. автогенерация документации

6.1. автогенерация кода все-таки получше ибо: 1) позволяет генерить код для разных языков. 2) Легко и нативно расширяема, в отличии от кода, который предназначен совсем для другого.

7. единый механизм авторизации

7.1. придумать

7.2. требования от Докучаева

7.2.1. регистрация и авторизация в 1 шаг

7.2.2. ничего 1 в 1 не преносим из v1

7.2.3. signup всегда выолняется с переданной в него сессией

8. проверка инвалидации кешей в compile-time

8.1. Есть два варианта архитектуры, которые решают данную проблему.

8.2. макросы!

8.2.1. макросы - всего-лишь инструмент.

8.2.1.1. который может помочь решить вопрос с меньшими затратами, чем без макросов

8.2.1.1.1. теоретически?:) или ты видишь решение?

8.3. ИТОГО

8.3.1. посмотрим typed-actors. попробуем оттуда утянуть кусок

8.3.2. строковая интерполяция с пакросами

8.3.3. cспереть кусок из https://github.com/kciesielski/macmemo

8.4. избавление от жестких ссылок внутри сервисов/модулей, используемых только для построения правил инвалидации кэшей

8.4.1. Произойдет автоматически при изменении архитектуры

9. запрос пинга без продления жизни сессии

9.1. выдаем сессию только по запросу /session и более никогда не генерить новую

10. схема для описания протокола

10.1. по которой фронты смогут сгенерить код

10.1.1. protobuf?

10.1.2. XSD?

10.1.3. json-schema?

10.1.4. trift?

10.1.5. shacl + json-ld

10.1.6. netflix/falcor

10.1.7. swagger

10.2. надо либо генерить при компиляции, либо аккуратно писать тесты типа ApiJsonTest

10.2.1. один из подходов к генерации схемы, это генерить схему на основе тестов - поскольку в тестах требования к данным и методам очевидно должны быть формализованы в достаточной степени.

10.2.1.1. Спорный подход конечно

10.2.1.2. это будет удобнее \ проще \ стабильнее чем по модели?

10.2.1.2.1. сомнительно

10.3. ИТОГО

10.3.1. JSON-schema

10.3.1.1. jackson

10.3.1.1.1. экстендим своими типами

10.3.1.1.2. аннотации для текста и др

10.3.1.1.3. натравливаем на объект Request и Response

10.3.1.2. пистаь свое на макросах

10.3.1.2.1. todo

10.3.1.3. как-то на тестах автоматом проверялась обратную совместимость. Без написания тестов каждый раз

10.3.1.3.1. пишем сами таск в sbt, который все проверяет, и если не сломалось обновляет правила

11. каждая операция может иметь клиентский requestId. Если операция вызывается 2й раз с предыдущим requestId, то возвращать результат предыдущей операции

11.1. много памяти под кеш?

11.2. И в каждом респонсе возвращать ИД запросившей операции. В будещем это позволить скореллировать сообщения при работе через вебсокет.

11.3. Не совсем понятно для чего это. Операции бывают двух типов: Команды (с сайд эффектами) и Запросы (данных). Держать результат выполнения Команды в кеше имеет смысл для идемпотентности Команды (если клиент не смог получить ответ, а Команда выполнилась успешно). Но только для последней успешной Команды по конкретному запросу (это много кеша не потребует). Для Запросов requestId смысла вводить не вижу честно говоря.

11.3.1. это плохая практика - принудительное натягивания паттерна request/response на асинхронное взаимодействие. Сокеты дают бОльшие возможности - так давайте ими пользоваться.

11.3.2. Если делать запрос через вебсокет = можно коррелировать запрос-ответ на клиенте. И кроме того можно коррелировать сообщения скажем в смартформе или в создании депозита. Что сейчас некая плохоосознаваемая проблема

11.4. итого

11.4.1. делаем когда будем переносить платежи

11.4.2. только для запросов-команд

11.4.3. делаем ближе к переносу платежей

12. типизация

12.1. единый формат номера мобильного

12.1.1. На вход подается объект разделенный на код страны, номер оператора, номер абоеннта

12.2. даты в читаемом виде (xsd-формат?)

12.2.1. ISO 8601?

12.2.2. Можно расширить сериализацию Time для даты в читабельном виде

12.3. ИТОГО

12.3.1. Даты в схеме прописываем как строки с регекспом

12.3.1.1. пример

12.3.1.1.1. <startdate>2002-05-30T09:30:10+06:00</startdate>

12.4. смещение относительно текущей даты

12.4.1. как в спланке

12.5. дата рождения отдельный тип

12.5.1. от строки

12.5.2. невычисляемый

13. требования/хотелки

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

13.1.1. бизнес это не одобрит:)

13.1.2. можно возвращать ответ сразу, но с каким-нибудь http кодом, например 405, 403 или 418 :)

13.2. выделение ядря АПИ в модуль для создания отдельных приложений

13.2.1. типа активатора

13.2.2. 2 модуля

13.2.2.1. ядро

13.2.2.2. бизнеслогика

13.3. галочка, чтобы поднимать приложение горячим или холодным

13.3.1. для локального запуска

13.3.2. за счет модулей

14. ВСЕ АСИНХРОННОЕ

14.1. асинхронность только там, где нужна.

14.1.1. определается архитектурой и нотациями

15. при переносе удаляем лишние данные из модели.

15.1. Никаких справоччников в запросах с данными

15.1.1. например, в operations не возвращаем всю сущность провайдера

16. Новый конфиг

16.1. все в typesafe config?

16.2. Как

17. механизм лимитов

17.1. модуляризовать

17.2. хочется иметь возможность для каждой апишки иметь свою схему в БД

18. Авторизация основанная на ролях(RSBAC based)

19. Описание сценариев

19.1. Для связи последовательности вызовов хэндлеров одним контекстом

19.2. Для генерации клиентского кода

19.3. Для упрощения автоматического тестирования

19.3.1. Нагрузочные тесты

19.3.2. Регресс тесты

19.3.3. Сервис тесты

20. пинг сессии без ее продления

21. клиент может передавать опциональный ид запроса, который мы вернем в ответе

21.1. необходимо для связи запроса и ответа, например в режиме асинхронной работы с вебсокетами.

21.1.1. для запросов через вебсокеты поле обязательно

22. Сессия в http-onle куке

23. В ядре протокола должен быть флаг аля fallBackData=true|false

24. модуль лимитов

24.1. настраивать стратегии

24.1.1. строгая проверка

24.1.1.1. медленнее

24.1.2. нестрогая проверка

24.1.2.1. быстрее

25. Если есть userRequestId, то отвечать предыдушим ответом на повторные запросы по АКТИВНЫМ операциям