Это третья статья из серии статей про REST API:
В этой статье мы рассмотрим подход к разработке REST API на основе контракта.
При разработке хорошего API REST важно иметь отличные микросервисы. Подход Contract First поможет вам разработать хороший контракт до его реализации. Однако это не так просто!
![](https://habrastorage.org/r/w1560/webt/sy/lf/69/sylf69uh1e-x_r2tajmhyic7c8q.png)
Есть несколько видов веб-сервисов, среди которых REST и SOAP. Для каждого сервиса есть:
Потребитель должен знать детали предоставляемой услуги. По этой причине должен быть заключен договор. Договор на обслуживание определяет:
При подходе «Contract First» (контракт сначала) вы сначала определяете контракт, а затем внедряете сервис. Давайте рассмотрим пример.
Давайте сначала рассмотрим случай использования WSDL — языка определения веб-сервисов. Вот пример использования:
![](https://habrastorage.org/r/w1560/webt/89/kg/06/89kg06voobbtvb7brgn6pry_ogu.png)
WSDL обычно используется с веб-сервисами SOAP/XML. В таком случае вы обычно определяете:
![](https://habrastorage.org/r/w1560/webt/gc/di/gv/gcdigvve_m9dhjssvtvwptixzwi.png)
Когда мы начинаем с заключения договора, мы определяем WSDL, а затем делимся им с нашим потребителем. Все это может произойти еще до того, как мы внедрим сервис и сделаем его доступным.
Контракт сообщает потребителю, каким ожидается обмен запросами и ответами. Как только договор заключен, поставщик услуг может работать над предоставлением услуги, соответствующей договору. Потребитель услуг может работать над разработкой приложения для его использования.
Поскольку кодирование происходит на основе контракта, поставщики услуг и группы потребителей услуг четко понимают подход и детали коммуникации. Следовательно, разработка может происходить одновременно.
Поскольку кодирование происходит на основе контракта, команды производителей и потребителей имеют представление об ожиданиях друг друга. В результате, если межгрупповое тестирование невозможно из-за разных темпов разработки, программное обеспечение-заглушка может использоваться для моделирования над поведения другой стороны на основе контракта.
Поскольку параметры сервиса зависят только от контракта, фактическая структура программного обеспечения, используемая для разработки сервиса, не имеет большого значения. Поставщик услуг и потребитель услуг могут использовать разные технологии.
Схемы, которые используются для определения договора на услугу, хорошо определены в WSDL. Следовательно, если части служб повторяются в других службах, то соответствующие схемы также можно использовать повторно.
Большая часть этих затрат будет сосредоточена вокруг соглашения об обслуживании. Вы должны убедиться, что договор четко определен и не меняется очень часто.
В течение срока пользования сервиса, если вы обновляете договор, это влияет на все другие заинтересованные стороны. Следовательно, должен существовать надлежащий механизм для передачи изменений различным потребителям.
По этому вопросу имеется авторское видео.
В этой статье мы обсудили подход Contract First в контексте веб-сервисов.
Rapid Application Development With API First Approach Using Open-API Generator
Implementing an API-First Design Methodology
- Введение в REST API — RESTful веб-сервисы
- Различия REST и SOAP
- Разработка REST API — что такое Contract First (контракт в первую очередь)?
- Разработка REST API — что такое Code First (код в первую очередь)?
- REST API — Что такое HATEOAS?
- Рекомендации по REST API — примеры проектирования веб-сервисов на Java и Spring
В этой статье мы рассмотрим подход к разработке REST API на основе контракта.
При разработке хорошего API REST важно иметь отличные микросервисы. Подход Contract First поможет вам разработать хороший контракт до его реализации. Однако это не так просто!
![](https://habrastorage.org/webt/sy/lf/69/sylf69uh1e-x_r2tajmhyic7c8q.png)
Вы изучите
- Что такое Contract First подход к разработке REST API?
- Каковы преимущества подхода Contract First?
- Каковы недостатки подхода Contract First?
- Когда вы использовать подход Contract First?
Понятие веб-сервисов
Есть несколько видов веб-сервисов, среди которых REST и SOAP. Для каждого сервиса есть:
- Поставщик сервиса, который предоставляет сервис
- Потребитель сервиса, который им пользуется
Потребитель должен знать детали предоставляемой услуги. По этой причине должен быть заключен договор. Договор на обслуживание определяет:
- Каковы входы и выходы из сервиса?
- По какому URL-адресу доступен сервис?
- Как отправлять авторизацию?
Contract First подход
При подходе «Contract First» (контракт сначала) вы сначала определяете контракт, а затем внедряете сервис. Давайте рассмотрим пример.
WSDL
Давайте сначала рассмотрим случай использования WSDL — языка определения веб-сервисов. Вот пример использования:
![](https://habrastorage.org/webt/89/kg/06/89kg06voobbtvb7brgn6pry_ogu.png)
WSDL обычно используется с веб-сервисами SOAP/XML. В таком случае вы обычно определяете:
![](https://habrastorage.org/webt/gc/di/gv/gcdigvve_m9dhjssvtvwptixzwi.png)
Что подразумевается под контрактом?
Когда мы начинаем с заключения договора, мы определяем 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