Versioning - Speaker Deck

Slide 1

Slide 1 text

API Versioning Warsaw ~ Kyiv, May 2020 Oleg Kovalov Allegro https://olegk.dev

Slide 2

Slide 2 text

- Gopher for ~5 years - Open source contributor - Engineer at allegro.pl core team https://olegk.dev Кто я 2

Slide 3

Slide 3 text

- Продукт меняется - Выкатывать изменения по чуть-чуть - Упростить миграцию, а еще чтобы не развалилось Кто этот Versioning 3

Slide 4

Slide 4 text

- Команд много, а сервисов еще больше - Люди ошибаются, техника тоже - Конечно же автоматизация Версионирование это важно 4

Slide 5

Slide 5 text

- Договариваемся какое API - Вот тут у нас поле будет строкой - А тут мы хотим вот такой параметр - Прочитайте README.md там “все” есть - А если чего-то нет - решим как будет правильно Джентельменское соглашение 5

Slide 6

Slide 6 text

Pros: - Простое и рабочее - Хорошо для маленьких проектов Cons: - Никаких железобетонных гарантий - Неустойчиво к человеческим ошибкам Джентельменское соглашение 6

Slide 7

Slide 7 text

- А что если использовать схему - А давайте генерировать код сами - А можно еще валидировать схему - А пусть версия будет в Content-Type - А может лучше параметром в URL - А можно даже полем в JSON - А вот в другой команде... - ... - А может что-то лучше? А давайте напишем свой велосипед 7

Slide 8

Slide 8 text

Pros: - можно покодить - работает для нашего случая Cons: - нужно покодить - работает для нашего случая (и только) А давайте напишем свой велосипед 8

Slide 9

Slide 9 text

- У нас есть 1 спецификация для всех - Уже готов туллинг от сообщества и нуждающихся - Остаётся только завести к себе в prod - Делаем схему, а по ней генерируем клиент/сервер - Делаем сервер/клиент, по нему генерируем схему - ¯\_(ツ)_/¯ OpenAPI Speciﬁcation 9

Slide 10

Slide 10 text

Slide 11

Slide 11 text

Slide 12

Slide 12 text

- Изменим префикс URL - было /v1/pet - стало /v2/pet - Версионирование OpenAPI 12

Slide 13

Slide 13 text

Pros: - Работает для огромного большинства случаев - Проверен потом и кровью - Схема == закон Cons: - Нужно начать делать - Нужно понять, что вам он нужен OpenAPI 13

Slide 14

Slide 14 text

- JSON-RPC - откажемся от REST - gRPC - решение от Google - Thrift - как gRPC, только от Apache Foundation - GraphQL - Facebook & co - ... Есть ли жизнь после OpenAPI ? 14

Slide 15

Slide 15 text

- REST -> RPC - Уже Protobuf - добавление полей бесплатно - HTTP1/2 -> HTTP2 - Кодогенерация - Бинарный gRPC 15

Slide 16

Slide 16 text

syntax = "proto3"; service Greeter { rpc SayHello (HelloRequest) returns (HelloReply); } message HelloRequest { string name = 1; } message HelloReply { string message = 1; } Обычный proto файл 16

Slide 17

Slide 17 text

syntax = "proto3"; service Greeter { rpc SayHello (HelloRequest) returns (HelloReply); } message HelloRequest { string name = 1; } message HelloReply { string message = 1; string personalized = 2; } Обычный proto файл v2 17

Slide 18

Slide 18 text

Pros: - RPC, Protobuf - Performance++ - Все и вместе Cons: - Не все языки, а значит и клиенты (но уже работает в браузерах) - Дополнительный туллинг gRPC 18

Slide 19

Slide 19 text

- Универсальный / гибкий - Возможность передать батч запросов - Data, not a view - RFC3339 для даты это круто, но timestamp универсальнее - Не стоит форматировать и добавлять HTML - One way to do it - странно иметь /preferences - и параллельно /settings?user=foo - когда оба делают одно и тоже Хороший протокол 19

Slide 20

Slide 20 text

- Приспособлен к изменениям - - Не удаляем старое поведение - к примеру в gRPC не надо удалять старые поля - по стоимости будет 0.00$ - Всегда стоит подумать о миграции на новую версию Хороший протокол 20

Slide 21

Slide 21 text

- Идея ведь хорошая - Но далеко не для всех - Слишком много клиент знает Брать можно и полезно, но делать аккуратно. Немного о Graphql 21

Slide 22

Slide 22 text

- Свои велосипеды это интересно - Но до поры, до времени - Серебряной пули нет - gRPC хорош Выводы 22

Slide 23

Slide 23 text

Thank you Questions? https://olegk.dev That’s all folks