Нужно ли вообще разрабатывать клиентскую библиотеку для служб REST, чтобы помочь предотвратить поломки API?

9

У нас есть проект, в котором код пользовательского интерфейса будет разрабатываться той же командой, но на другом языке (Python / Django) из уровня сервисов (REST / Java). Код для каждого слоя выходит из разных хранилищ кода и может следовать разным циклам выпуска. Я пытаюсь придумать процесс, который будет предотвращать / сокращать критические изменения на уровне сервисов с точки зрения уровня пользовательского интерфейса.

Я подумал написать интеграционные тесты на уровне пользовательского интерфейса, которые мы будем запускать всякий раз, когда мы создаем пользовательский интерфейс или сервисный уровень (мы используем Jenkins в качестве инструмента CI для создания кода, который находится в двух репозиториях Git), и если возникают сбои, затем что-то на уровне сервисов ломается и фиксация не принимается.

Было бы также хорошей идеей (является ли это наилучшей практикой?), Чтобы разработчик уровня служб создавал и обслуживал клиентскую библиотеку для службы REST, которая существует на уровне пользовательского интерфейса, которую они будут обновлять всякий раз, когда происходит критическое изменение в их сервис API? Вероятно, тогда у нас было бы преимущество статически типизированного API, на основе которого строится код пользовательского интерфейса. Если API клиентской библиотеки изменится, код пользовательского интерфейса не будет скомпилирован (поэтому мы скоро узнаем, что произошло критическое изменение). Я также по-прежнему выполняю интеграционные тесты при создании уровня пользовательского интерфейса или сервисов, чтобы дополнительно проверить, что интеграция между пользовательским интерфейсом и сервисами все еще работает.

rest django

— Лучшие практики
источник

6

Разве вам не сообщают, когда изменение API сделано? В этих случаях часто лучше создать версию API, чтобы у вашего пользовательского интерфейса всегда была рабочая версия. Затем «обновите» до последней версии API как можно скорее.

— Мэтт С

@MattS: я согласен с вами. Но со связью или без нее: выполнить обновление до измененного API намного проще, когда компилятор сообщает вам точно все места, которые вы должны изменить в своем коде. Хотя ОП все еще не сообщает нам, как его код на Python будет предоставлять статически типизированный API.

— Док Браун

1

В общем, для методов API, которые уходят, выберите соглашение и «осуждайте» их, особенно, когда полный и доступный API замены доступен и протестирован. Оставьте старый API на месте (по существу), но пометьте метаданные сигнатуры метода или вставьте событие регистрации, чтобы можно было четко определить использование.

Ведение журнала в сервисном API - это одно, а оповещение потребляющих клиентов - другое. Для REST я не думаю, что есть надежная, стандартная практика. Клиенты FourSquare API могут обнаруживать устаревшие методы, даже если вызываемый метод успешен (код HTTP 200, однако errorType будет установлен как «устаревший»). Возможно разумная стратегия для предоставления потребителям возможности узнать об устаревшем методе в API, не вызывая нарушения.

https://developer.foursquare.com/overview/responses

В руководстве по API предложите дату или номер выпуска сборки, в котором устаревший API будет полностью удален. Когда вы дорабатываете свою стратегию по устареванию, вы захотите предупредить потребителей API о том, что такое предлагаемая стратегия (как они могут обнаружить устаревшие методы, как перейти к API замены и когда устаревший API больше не будет доступен, если очищается во время очистки API), и запрашивайте отзывы от них, чтобы гарантировать, что процесс полезен для всех.

— JustinC
источник

1

Управление версиями вашего API - еще одна возможность. Когда новая версия развернута, оставьте старую версию активной и разрешите согласование через запрос. Если вы поддерживаете последние 2 или 3 версии, тогда код пользовательского интерфейса может обновляться в своем собственном темпе.

— Jiggy
источник

1

Есть как минимум три вопроса одновременно, давайте сделаем их один за другим

"Это хорошая идея иметь клиентскую библиотеку для службы REST?"

Скорее всего, да, если вы не хотите, чтобы произвольные вызовы REST напрямую рассеялись по всему коду вашего интерфейса.

"Это хорошая идея, чтобы позволить разработчику уровня служб создавать и поддерживать lib?"

Это зависит от людей в вашей команде. Сопровождающий API должен знать как то, что доступно на уровне сервисов, так и требования уровня UI. Таким образом, это может быть либо человек из уровня услуг, либо из уровня пользовательского интерфейса, либо (в зависимости от размера и других задач) человек независимо от обеих команд.

[получим ли мы преимущество от того факта, что] «если API клиентской библиотеки изменится, код пользовательского интерфейса не скомпилируется»

Разве вы не сказали, что пользовательский интерфейс будет написан на Python? Это не статически типизированный язык, поэтому я не ожидал бы немедленного прерывания сборки после изменения API. Я предполагаю, что я ошибся в этом вопросе, и у вас есть статически типизированный API здесь - тогда вы можете получить некоторые преимущества здесь, если сборка не нарушается при добавлении некоторых новых функций (таких как новые необязательные параметры) в API. В противном случае вы создадите много ненужных накладных расходов для своей команды.

— Док Браун
источник