Разработка REST API — что такое Contract First?

Автор оригинала: Ranga Karanam
  • Перевод
  • Tutorial
Это третья статья из серии статей про REST API:


В этой статье мы рассмотрим подход к разработке REST API на основе контракта.

При разработке хорошего API REST важно иметь отличные микросервисы. Подход Contract First поможет вам разработать хороший контракт до его реализации. Однако это не так просто!



Вы изучите


  • Что такое Contract First подход к разработке REST API?
  • Каковы преимущества подхода Contract First?
  • Каковы недостатки подхода Contract First?
  • Когда вы использовать подход Contract First?

Понятие веб-сервисов


Есть несколько видов веб-сервисов, среди которых REST и SOAP. Для каждого сервиса есть:

  • Поставщик сервиса, который предоставляет сервис
  • Потребитель сервиса, который им пользуется

Потребитель должен знать детали предоставляемой услуги. По этой причине должен быть заключен договор. Договор на обслуживание определяет:

  • Каковы входы и выходы из сервиса?
  • По какому URL-адресу доступен сервис?
  • Как отправлять авторизацию?

Contract First подход


При подходе «Contract First» (контракт сначала) вы сначала определяете контракт, а затем внедряете сервис. Давайте рассмотрим пример.

WSDL


Давайте сначала рассмотрим случай использования WSDL — языка определения веб-сервисов. Вот пример использования:



WSDL обычно используется с веб-сервисами SOAP/XML. В таком случае вы обычно определяете:



Что подразумевается под контрактом?


Когда мы начинаем с заключения договора, мы определяем WSDL, а затем делимся им с нашим потребителем. Все это может произойти еще до того, как мы внедрим сервис и сделаем его доступным.

Контракт сообщает потребителю, каким ожидается обмен запросами и ответами. Как только договор заключен, поставщик услуг может работать над предоставлением услуги, соответствующей договору. Потребитель услуг может работать над разработкой приложения для его использования.

Преимущества подхода Contract First


Команды могут разрабатывать параллельно


Поскольку кодирование происходит на основе контракта, поставщики услуг и группы потребителей услуг четко понимают подход и детали коммуникации. Следовательно, разработка может происходить одновременно.

Команды знают, что ожидать


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

Кроссплатформенная совместимость


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

Позволяет повторно использовать схемы


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

Недостатки подхода Contract First


Требуется дополнительные начальные затраты


Большая часть этих затрат будет сосредоточена вокруг соглашения об обслуживании. Вы должны убедиться, что договор четко определен и не меняется очень часто.

Механизм для обновления контракта и обмена


В течение срока пользования сервиса, если вы обновляете договор, это влияет на все другие заинтересованные стороны. Следовательно, должен существовать надлежащий механизм для передачи изменений различным потребителям.

По этому вопросу имеется авторское видео.

Резюме


В этой статье мы обсудили подход Contract First в контексте веб-сервисов.

Дополнительное чтение


Rapid Application Development With API First Approach Using Open-API Generator

Implementing an API-First Design Methodology

Комментарии 3

    +1

    С одной стороны статья чётко по делу разжёвывает каждую деталь, а с другой очень короткая.
    Правильная мысль про контракт вперёд!
    Я не раз убеждался, что если не договориться о контракте на берегу то разработка превращается в хаос.

      +1
      Две мысли:
      — как можно было усложнить такую простую идею?
      — неужели есть люди, которые правда не планируют контракт API до его реализации? И что они делают в IT?
        0

        Рядом же есть статья про code first. Бывают ситуации, когда полностью спроектировать контракт до реализации бессмысленно, дорого, или просто не нужно. По аналогии — contract first это водопад, со всеми его последствиями

      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

      Самое читаемое