Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Versioning

64a4ba69d50590e592cd8e572454daa8?s=47 Oleg
May 26, 2020

 Versioning

64a4ba69d50590e592cd8e572454daa8?s=128

Oleg

May 26, 2020
Tweet

Transcript

  1. API Versioning Warsaw ~ Kyiv, May 2020 Oleg Kovalov Allegro

    https://olegk.dev
  2. - Gopher for ~5 years - Open source contributor -

    Engineer at allegro.pl core team https://olegk.dev Кто я 2
  3. - Продукт меняется - Выкатывать изменения по чуть-чуть - Упростить

    миграцию, а еще чтобы не развалилось Кто этот Versioning 3
  4. - Команд много, а сервисов еще больше - Люди ошибаются,

    техника тоже - Конечно же автоматизация Версионирование это важно 4
  5. - Договариваемся какое API - Вот тут у нас поле

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

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

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

    - нужно покодить - работает для нашего случая (и только) А давайте напишем свой велосипед 8
  9. - У нас есть 1 спецификация для всех - Уже

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

  11. 11

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

    - Версионирование OpenAPI 12
  13. Pros: - Работает для огромного большинства случаев - Проверен потом

    и кровью - Схема == закон Cons: - Нужно начать делать - Нужно понять, что вам он нужен OpenAPI 13
  14. - JSON-RPC - откажемся от REST - gRPC - решение

    от Google - Thrift - как gRPC, только от Apache Foundation - GraphQL - Facebook & co - ... Есть ли жизнь после OpenAPI ? 14
  15. - REST -> RPC - Уже Protobuf - добавление полей

    бесплатно - HTTP1/2 -> HTTP2 - Кодогенерация - Бинарный gRPC 15
  16. syntax = "proto3"; service Greeter { rpc SayHello (HelloRequest) returns

    (HelloReply); } message HelloRequest { string name = 1; } message HelloReply { string message = 1; } Обычный proto файл 16
  17. 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
  18. Pros: - RPC, Protobuf - Performance++ - Все и вместе

    Cons: - Не все языки, а значит и клиенты (но уже работает в браузерах) - Дополнительный туллинг gRPC 18
  19. - Универсальный / гибкий - Возможность передать батч запросов -

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

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

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

    времени - Серебряной пули нет - gRPC хорош Выводы 22
  23. Thank you Questions? https://olegk.dev That’s all folks