Кирилл Лихтарович «Версионирование и кодогенерация в REST API»

Кирилл расскажет о проблемах версионирования REST API на примерах, покажет какие способы версионирования он применяет и в чём их отличие друг от друга. Познакомимся с разницей между code first и contract first подходов и о том, почему он выбрал contract first как основной для проектирования новых API. Расскажет о кодогенерации и сделает акцент на связке кодогенерации с версионированием. Покажет приниципиальную схему кодогенератора, позволяющего прозрачно и понятно поддерживать разные версии вашего API.

Transcript

1. © 2020 Veeam Software. Confidential information. All rights reserved. All trademarks are the property of their respective owners. Кирилл Лихтарович Experienced developer Telegram: @likhtarovich Версионирование и кодогенерация в REST API
2. © 2020 Veeam Software. Confidential information. All rights reserved. All trademarks are the property of their respective owners. Veeam в числах 400,000+ Клиентов в мире, 82% Клиентов из Fortune 500 Санкт-Петербург Прага Офисы R&D: 35+ Стран присутствия 4400+ Сотрудников В 3.5 раза Выше удовлетворенность клиентов, чем в среднем по индустрии 13 28 66 145 298 515 833 986 1259 2020 2600 3000 3500 4,3K+ 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 Veeam ONE Veeam Agent for Windows Veeam Agent for Linux VB for Microsoft Office 365 VA Console Orchestrator VA for Nutanix Veeam Agent for Unix Veeam FastSCP Veeam Monitor for VMware Veeam Reporter Veeam Management Pack Veeam Backup & Replication Сотрудники Продукты $1+ млрд. Выручка в 2019
3. 3 REST API в Veeam Veeam Backup & Replication Veeam Service Provider Console Veeam Availability Orchestrator Veeam Backup for Microsoft Office 365 Veeam ONE Veeam Backup Enterprise Manager
4. 4 Структура доклада 1. Версионирование 1. Обратная совместимость 2. Методы версионирования для REST API 3. Два способа проектирования REST API 2. Кодогенерация 1. Схема кодогенератора 2. С чего начать собственную реализацию
5. 5 Версия ПО ProductVersion Major.Minor.Build MyService 3.1.0-rev-8 Windows 10.0.18362.476
6. 6 Обратная совместимость REST API Client library v1.0 REST API Service v1.0 REST API Service v1.1 REST API specification v1.0 REST API Client library v1.1 REST API specification v1.1
7. 7 Обратная совместимость
8. 8 Виды изменений Ломающие: нарушающие предыдущий контракт Неломающие: дополняющие предыдущий контракт
10. 10 Неломающие изменения в REST • добавление новых путей, ресурсов и действий над ними • расширение существующих моделей • добавление/изменение/удаление ссылок (если HATEOS)
11. 11 Методы версионирования https://api/v2/Tasks/{TaskId} https://api/Tasks/{TaskId}?v=2 application/App.v2.param.json HTTP x-api-version: 2
12. 12 Версия в URI HTTP POST https://storage.googleapis.com/storage/v1/b DELETE /2015-03-31/functions/FunctionName?Qualifier=Qualifier HTTP/1.1
13. 13 Версия в Query Path HTTP GET https://status.dev.azure.com/_apis/status/health?services={services}&api-version=6.0-preview.1 HTTP GET https://autoscaling.amazonaws.com/?Action=SetInstanceHealth&InstanceId=i-12345678 &HealthStatus=Unhealthy&Version=2011-01-01
14. 14 Версия в Media Type
15. 15 Версия в X-Header
16. 16 Комбинирование версий
17. 17 Реализации версионирования Инкапсуляция предыдущей версии Расширение предыдущего контракта Отдельные модели и контроллеры для нового контракта Расширение предыдущей версии Трансформация моделей между версиями
18. 18 НА ЭТАПЕ ПРОЕКТИРОВАНИЯ Неверный метод версионирования Отсутствие фиксации «контрактов» Проектирование доменной области без учета новых версий Инкапсуляция предыдущей версии read-only read-only read-only read-only
19. 19 Расширение предыдущей версии
20. 20 Проектирование REST API Code-First Contract-First
21. 21 Code-First подход Code-First
22. 22 Contract-First подход Contract-First
23. 23 Почему Contract-first  разработка клиента и сервера одновременно  документация прямо в спецификации  новые фичи – прямо в спецификации  гарантированность контракта
25. © 2020 Veeam Software. Confidential information. All rights reserved. All trademarks are the property of their respective owners. Кодогенерация
28. 28  Быстро добавлять новые ресурсы и пути  Избежать дублирования бизнес-логики  Минимизировать версионные изменения  Гарантировать обратную совместимость Основные требования
29. 29 Business-Logic Mapping From Version 1.2 To Version 1.3 Принципиальная схема Mapping From Version 1.3 To Latest read-only read-only
30. 30 Business-Logic Virtual controller
31. 31 Virtual controller
32. 32 Business-Logic Абстракция бизнес-логики
33. 33 Абстракция бизнес-логики
34. 34 Business-Logic Mapping From Version 1.2 To Version 1.3 Принципиальная схема Mapping From Version 1.3 To Latest read-only read-only
35. 35 Business-Logic Абстракция моделей
36. 36 Абстракция моделей
37. 37 Business-Logic Трансформация моделей Mapping From Version 1.2 To Latest
38. 38 Mapping From Version 1.2 To Version 1.3 Трансформация моделей Mapping From Version 1.3 To Latest Business-Logic read-only read-only
39. 39 Business-Logic Mapping From Version 1.2 To Version 1.3 Принципиальная схема Mapping From Version 1.3 To Latest read-only read-only
40. 40 Полезные ресурсы для старта https://github.com/swagger-api/swagger-codegen https://github.com/RicoSuter/NSwag https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Versioning https://www.nuget.org/packages/AutoMapper/ КОДОГЕНЕРАТОРЫ: ПОДДЕРЖКА ВЕРСИЙ: ТРАНСФОРМАЦИЯ МОДЕЛЕЙ: РЕДАКТОР СПЕЦИФИКАЦИИ ДЛЯ CONTRACT-FIRST РАЗРАБОТКИ: https://editor.swagger.io/ https://swagger.io/blog/api-design/design-first-or-code-first-api-development/
41. 41 Мнение о кодогенераторе «Он нам очень сильно сократил время разработки рест сервиса. Если бы делали с нуля, то думаю там несколько месяцев ушло бы, а так пара недель и уже можно было делать UI и дёргать какие-то сервисные методы...» Семен П., Разработчик «Contract-first подход в разработке оказался очень удобным, просто описываешь спецификацию, а потом реализуешь бизнес-логику. Не надо вручную создавать контроллеры и модели» Александр Ш., Разработчик «Кодогенератор мы используем двух проектах. Он позволяет значительно ускорить работу и избавляет от необходимости писать рутинный код. Также автоматизированная генерация исключает возникновение ошибок в сгенерированном коде, особенно при рефакторинге – достаточно внести изменения в спецификацию и сгенерировать новые классы» Андрей П., Разработчик
43. © 2020 Veeam Software. Confidential information. All rights reserved. All trademarks are the property of their respective owners. Спасибо!