Это четвертая статья в серии статей по REST API:
В этой статье мы продолжим знакомство с разработкой REST API и рассмотрим подход Code-First.
Разработка хорошего REST API важна для того, чтобы иметь хорошие микросервисы. Подход Code-First фокусируется на генерации контракта из кода. Это наилучший из возможных подходов?
Всякий раз, когда вы разрабатываете сервис, такой как REST API или SOAP API, вы можете выбрать один из двух подходов:
Давайте начнем с быстрого примера для Code First.
Мы разрабатываем RESTful веб-сервис, используя Spring Boot Framework для генерации API. Например, в API retrieveAllUsers () мы открываем URI «/users» и
возвращаем всех пользователей (ресурс /users),
вызывая метод сервиса.
Когда мы переходим на этот URL, мы возвращаем всех пользователей:
Аналогичным образом определены и другие сервисные методы, каждый из которых имеет свой собственный URI. В этом примере мы берем код и генерируем из него документацию. В этой документации указано, как пользователь может использовать сервис. Для этого мы используем формат документации Swagger:
Swagger позволяет нам генерировать документацию из кода. Например, вот что Swagger генерирует для запроса на получение всех пользователей:
Он выводит тип получаемого нами ответного сообщения и сопровождающий его статус ответа. Вы даже можете вызвать этот сервис из Swagger получить ответ:
Вы также можете отправить запрос POST в "/users":
Swagger сообщит нам, как структурировать сообщение запроса и указать внутри него отдельные форматы полей. Он также сообщит вам тип ответа, который вы получите, вместе с кодом ответа. То, что Swagger генерирует из кода, называется контрактом.
Основные преимущества этого подхода:
Недостатки этого подхода заключаются в следующем:
Производитель услуг и потребители услуг не могут разрабатывать параллельно. Сначала необходимо разработать сервис, затем сгенерировать контракт, и только после этого можно написать код потребителя, который будет придерживаться контракта. Без понимания контракта потребитель не может быть разработан.
Поскольку договор не может быть известен до того, как сервис будет разработан, не существует цели для различных заинтересованных сторон в разработке. Следовательно, есть все шансы, что направления будут отклоняться, и будут внесены ненужные изменения, что приведет к напрасной трате усилий.
На некоторых старых платформах не так просто сгенерировать контракт из кода. В результате этого для сгенерированных контрактов довольно часто возникает несовместимость между платформами.
По этому вопросу имеется авторское видео.
В этой статье мы исследовали Code First подход построения REST API. Несмотря на то, что подход, основанный на коде, эффективен с точки зрения разработчика, он сталкивается с серьезными проблемами, когда речь идет о совместной разработке поставщика и потребителя.
API Development: Design-First or Code-First?
How to Develop a RESTful Web Service in ASP.NET Web API
- Введение в REST API — RESTful веб-сервисы
- Различия REST и SOAP
- Разработка REST API — что такое Contract First (контракт в первую очередь)?
- Разработка REST API — что такое Code First (код в первую очередь)?
- REST API — Что такое HATEOAS?
- Рекомендации по REST API — примеры проектирования веб-сервисов на Java и Spring
В этой статье мы продолжим знакомство с разработкой REST API и рассмотрим подход Code-First.
Разработка хорошего REST API важна для того, чтобы иметь хорошие микросервисы. Подход Code-First фокусируется на генерации контракта из кода. Это наилучший из возможных подходов?
Вы изучите
- Что такое Code-First подход к разработке REST API?
- Каковы преимущества подхода Code-First?
- Каковы недостатки подхода Code-First?
- Когда вы использовать подход Code-First?
Что такое Code-First подход?
Всякий раз, когда вы разрабатываете сервис, такой как REST API или SOAP API, вы можете выбрать один из двух подходов:
- Code First и генерируйте контракт из кода
- Contract First и разработка кода на основе контракта
Давайте начнем с быстрого примера для Code First.
Spring Boot Code First пример REST API
Мы разрабатываем RESTful веб-сервис, используя Spring Boot Framework для генерации API. Например, в API retrieveAllUsers () мы открываем URI «/users» и
возвращаем всех пользователей (ресурс /users),
вызывая метод сервиса.
Когда мы переходим на этот URL, мы возвращаем всех пользователей:
Аналогичным образом определены и другие сервисные методы, каждый из которых имеет свой собственный URI. В этом примере мы берем код и генерируем из него документацию. В этой документации указано, как пользователь может использовать сервис. Для этого мы используем формат документации Swagger:
Swagger позволяет нам генерировать документацию из кода. Например, вот что Swagger генерирует для запроса на получение всех пользователей:
Он выводит тип получаемого нами ответного сообщения и сопровождающий его статус ответа. Вы даже можете вызвать этот сервис из Swagger получить ответ:
Вы также можете отправить запрос POST в "/users":
Swagger сообщит нам, как структурировать сообщение запроса и указать внутри него отдельные форматы полей. Он также сообщит вам тип ответа, который вы получите, вместе с кодом ответа. То, что Swagger генерирует из кода, называется контрактом.
Преимущества Code First
Основные преимущества этого подхода:
- Контракты с минимальными усилиями: генерация контракта не требует дополнительных усилий. Это всего лишь побочный продукт разработки сервиса, так как он может быть автоматически сгенерирован из кода
- Синхронизация кода и контракта: поскольку контракт генерируется из кода, они всегда синхронизируются друг с другом
Недостатки Code First
Недостатки этого подхода заключаются в следующем:
Нет параллельной разработки
Производитель услуг и потребители услуг не могут разрабатывать параллельно. Сначала необходимо разработать сервис, затем сгенерировать контракт, и только после этого можно написать код потребителя, который будет придерживаться контракта. Без понимания контракта потребитель не может быть разработан.
Нет цели для команд
Поскольку договор не может быть известен до того, как сервис будет разработан, не существует цели для различных заинтересованных сторон в разработке. Следовательно, есть все шансы, что направления будут отклоняться, и будут внесены ненужные изменения, что приведет к напрасной трате усилий.
Нет кроссплатформенной совместимости
На некоторых старых платформах не так просто сгенерировать контракт из кода. В результате этого для сгенерированных контрактов довольно часто возникает несовместимость между платформами.
По этому вопросу имеется авторское видео.
Резюме
В этой статье мы исследовали Code First подход построения REST API. Несмотря на то, что подход, основанный на коде, эффективен с точки зрения разработчика, он сталкивается с серьезными проблемами, когда речь идет о совместной разработке поставщика и потребителя.
Дополнительное чтение
API Development: Design-First or Code-First?
How to Develop a RESTful Web Service in ASP.NET Web API
