Даниил Доронкин «Версионирование API»

В докладе будут расмотрены все тонкости версионирования програмного обеспечения. В частности семантическое версионирование, секрет его популярности и области применения. Конечно, затронем версионирование Web API и практические сценарии его использования. Разберём поддержку в библиотеке Microsoft ASP.NET API Versioning и её интеграцию с пакетом Swagger.

Transcript

1. 1 Версионирование API Доронкин Даниил www.rubius.com
2. 2 Что обсудим ▪ Версионирование; ▪ Подходы к управлению версиями; ▪ SemVer; ▪ Aspnet-api-versioning; ▪ Swagger интеграция. 2
3. 3 Ассоциации ▪ Уникальное имя; ▪ Эволюция ПО; ▪ Стадия готовности; ▪ Минимальное документирование. 3
4. 4 Примеры ▪ C# 7.2, Python 3.6.4; ▪ .net core 2.0.6, NodeJs 9.7.1; ▪ VueJs 2.0, Swashbuckle 2.3.0; ▪ http://sdb.amazonaws.com?...&Version=2009-04-15&... ; ▪ Corel Draw 11; ▪ Windows 2000; ▪ Delphi XE; ... 4
5. 5 Зачем управлять версиями ▪ Контроль изменений и жизненного цикла; ▪ Прозрачная работы с зависимостями. 5
6. 6 Dependency hell 6
7. 7 Demo 7
8. 8 8
9. 9 Инструменты ▪ Nuget; ▪ Npm; ▪ Gb. ... 9
10. 10 10
11. 11 Существующие подходы ▪ Целое число: Corel Draw 10; ▪ Текст: Delphi XE; ▪ Семантическое версионирование: .net core 2.0.6; ▪ Стадия разработки: AspNet.SignalR.Core 1.0.0-alpha1; ▪ Календарное версионирование: Rider 2018.1 ... 11
12. 12 SemVer ▪ X.Y.Z, где X, Y и Z – неотрицательные целые числа; ▪ X – мажорная версия, Y – минорная версия, Z – патч- версия; 12 1. 5. 4 major minor patch
13. 13 Patch версия ▪ Инкрементируем после баг-фиксов. 13
14. 14 Minor версия ▪ Добавление совместимой функциональности. 14
15. 15 Major версия ▪ Breaking changes. 15
16. 16 Расширение номера версии 16 ▪ Суффикс для отображения стадии разработки; 1.0.0-beta2 ▪ Сборочные метаданные. 1.0.0-beta+exp.sha.5114f85
17. 17 Изменения версии ▪ Версия 0.Y.Z до первого релиза; ▪ После релиза содержимое пакета не изменяется. 17
18. 18 Production? ▪ Да - укажите начальную версию 1.0.0; ▪ Нет - начните с версии 0.1.0. 18
19. 19 Функциональность устарела ▪ Увеличьте minor-версию: 1.0.0 -> 1.1.0; ▪ Увеличьте major-версию после удаления: 1.1.0 -> 2.0.0. 19
20. 20 Стадия разработки ▪ Укажите идентификатор в названии версии: 2.0.0-alpha; ▪ 2.0.0-alpha < 2.0.0-beta < 2.0.0 < 3.0.0-alpha < 3.0.0. 20
21. 21 Размер номера версии ▪ Без ограничений. * чем короче - тем лучше :) 21
22. 22 Внутренние зависимости обновлены 22 ▪ Могут быть рассмотрены как внутренние изменения; ▪ Обновлены для правки багов - patch-релиз.
23. 23 Breaking changes в minor релизе 23 ▪ Верните обратную совместимость в новом minor релизе; ▪ Отразите данную проблему в документации; ▪ Проинформируйте пользователей.
24. 24 Breaking changes вне спецификации 24
25. 25 Breaking changes вне спецификации 25 ▪ Ориентируйтесь по ситуации; ▪ Попробуйте решить проблему напрямую с клиентом; ▪ Обновите спецификацию в minor релизе и следом опубликуйте major релиз с исправлениями.
26. 26 SemVer 1.0.0 - 2.0.0 26 + Сборочные метаданные; 1.0.0+20130313144700 1.0.0-beta+exp.sha.5114f85 - SemVerTag. vX.Y.Z
27. 27 Преимущества ▪ Польза от номера версии; ▪ Формализованный набор правил; ▪ Простота. 27
28. 28 GitVersion SemVer по мотивам git истории. 28
29. 29 CalVer ▪ Упрощенная семантика; ▪ Чувствительность к дате. 29 2018. 1 year release
30. 30 Microsoft aspnet-api-versioning ▪ Управление версиями API; ▪ Open source; ▪ Open closed принцип; 30
31. 31 Подключение 31
32. 32 Конфигурация через атрибуты 32
33. 33 Передача версии в запросе 33
34. 34 Стратегии передачи версии 34 ▪ URL; ▪ Content negotiation; ▪ Query parameter.
35. 35 URL 35 ▪ https://app.com/api/v1.0/<params> - Отдельная точка доступа под каждую версию; - Не REST; + Версия всегда на виду; + Легко тестировать.
36. 36 Content negotiation 36 ▪ accept, content-type; - Тестировать сложнее; - Требуется обработка заголовков; + Один ресурс - одна точка доступа; + REST;
37. 37 Query parameter 37 ▪ https://app.com/api/<params>?api-version=1.0 - Размер URL; - Непрозрачное поведение если Query parameter не передан. + Одна и та же endpoint для всех версий; + Версия видна в адресной строке;
38. 38 Options конфигурация 38
39. 39 Устаревшая версия 39
40. 40 Версия по умолчанию 40
41. 41 Out of version 41
42. 42 Кастомизация ▪ Способ отправки версии в запросе; ▪ Кастомные version-атрибуты; ▪ Переопределение Error response; ... 42
43. 43 Swagger интеграция 43
44. 44 Swagger интеграция 44
45. 45 Demo 45
46. 46 Подводные камни ▪ Media type API version reader; ▪ Microsoft.AspNetCore.OData; ▪ Issues на Github. 46
47. 47 Преимущества ▪ Простой и удобный API. 47
48. 48 Преимущества ▪ Богатая функциональность; ▪ Кастомизация. 48
49. 49 Преимущества ▪ Безболезненное внедрение. 49
50. 50 Преимущества ▪ Swagger интеграция. 50
51. 51 Источники ▪ https://github.com/Microsoft/aspnet-api-versioning/wiki; ▪ https://semver.org/; ▪ https://gitversion.readthedocs.io/en/latest/; ▪ https://github.com/ddydeveloper/ApiVersioning; ▪ https://github.com/ddydeveloper/DependencyHellExample; ▪ https://www.youtube.com/watch?v=ngcigr_8oxw&t=109s. 51
52. 52 Спасибо за внимание www.rubius.com ddydeveloper@gmail.com 52