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

Versioning

 Versioning

Oleg Kovalov

May 26, 2020
Tweet

More Decks by Oleg Kovalov

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  10. 10

    View Slide

  11. 11

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide