Статьи

Ваш RESTful API делает то, что должен делать?

Август 23, 2017

Использование конечных точек API RESTful стало стандартом де-факто с 2008 года. С популярностью клиентских платформ на основе браузера (таких как AngularJS , Backbone.js или Ember.js ) конечные точки API RESTful нашли свое применение в корпоративных средах. , Используя Spring Tool Suite (STS) , довольно просто раскрутить веб-сервис RESTful. 

Цель этой статьи — поставить вопрос: «Ваш API RESTful делает то, что должен делать?»

Общие конечные точки RESTful и методы HTTP

Начальная коллекция конечных точек обычно обрабатывает обычные взаимодействия с базой данных для RESTful API. Некоторые примеры перечислены ниже:

  • Получить список записей или одну запись (GET)

  • Создать новую запись (POST)

  • Обновить существующую запись или набор записей (PATCH)

  • Удалить запись (УДАЛИТЬ)

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

Проверка сервиса RESTful

Обширные клиентские инфраструктуры часто предоставляют отличные механизмы для проверки данных. В сочетании с гладким интерфейсом (например, Bootstrap ) пользовательский интерфейс может быть весьма приятным. Часто разработчики начинают полагаться на проверку только на клиенте и забывают о RESTful API. Даже если ваш сервис изолирован от частной сети, проверка должна быть частью вашего RESTful API. 

Хорошее практическое правило — обращаться с вашим RESTful API так, как будто он работает в общедоступной сети. Аннотации упрощают добавление большинства правил проверки, а службы RESTful позволяют возвращать код ошибки HTTP при возникновении ошибки проверки. Хотя клиентская среда, вероятно, будет перехватывать эти ошибки перед отправкой, вы также можете обрабатывать эти ошибки.

Полезная нагрузка RESTful Service

Я видел пару подходов при доставке полезных данных обратно клиенту как часть вызова службы RESTful. Наиболее распространенным является возврат полезных данных, соответствующих базовому объекту. 

Например, если ваша конечная точка ищет список активных клиентов, полезная нагрузка может выглядеть примерно так, как указано ниже:

[
{
"id" : "1",
"name" : "ABC Company",
"isActive" : "true"
},
{
"id" : "2",
"name" : "My Company",
"isActive" : "true"
},
{
"id" : "3",
"name" : "Not My Company",
"isActive" : "true"
}
]

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

[
{
"responseCode" : "200",
"responseMessage" : "",
"pageNumber" : "1",
"totalPages" : "1",
"itemsPerPage" : "20",
"resultData" : [
{
"id" : "1",
"name" : "ABC Company",
"isActive" : "true"
},
{
"id" : "2",
"name" : "My Company",
"isActive" : "true"
},
{
"id" : "3",
"name" : "Not My Company",
"isActive" : "true"
}
]
}
]

Список активных клиентов содержится в списке resultData. Кроме того, полезная нагрузка содержит информацию для следующих элементов:

  • responseCode = код ответа HTTP

  • responseMessage = используется для передачи сообщений об ошибках или информационных сообщений

  • pageNumber = номер текущей страницы отображаемых данных

  • totalPages = общее количество страниц для исходного списка данных

  • itemsPerPage = количество элементов для данной страницы

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

Имена конечных точек

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

Распространенным заблуждением является создание конечных точек, которые действительно являются глаголами, например, возможно, конечной точкой process_invoice. Хотя этот подход популярен в удаленном вызове процедур (RPC), веб-службы RESTful не должны оставлять никаких побочных эффектов от вызова метода HTTP.

Я рекомендую просмотреть страницу веб-служб RESTful в Википедии  для получения дополнительной информации.

Документация

Даже если вы разрабатываете свой RESTful API только для внутреннего использования, рекомендуется включить документацию в процесс разработки. Такие продукты, как Swagger или MireDot, обеспечивают простой способ документирования ваших конечных точек с помощью JavaDocs и аннотаций. Документация может быть добавлена ​​в ваш процесс сборки, облегчая жизнь другим разработчикам в вашей команде. Фактически, моя собственная документация помогла мне, когда я оглядываюсь назад на обновления, которые были завершены несколькими спринтами в прошлом.

Модульное тестирование

Как и все объектно-ориентированные классы и методы, модульное тестирование всегда должно быть приоритетом. В Java наиболее распространенной структурой модульного тестирования является JUnit , которую я рекомендую использовать для тестирования конечных точек API RESTful.

Ранее в этом году Марк Палух представил отличную статью в начале этого года « Как протестировать REST API с помощью JUnit ».

Versioning

Управление версиями конечной точки RESTful API также получило широкое обсуждение в последнее время. Общее правило предполагает, что …

Если вам не нужно реализовывать управление версиями в своем API, не добавляйте его просто ради его добавления.

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

http://myhost/api/customers

Если бы мне нужно было включить управление версиями, а моя текущая версия была с API версии 2.0, следующие псевдонимы также будут действительны для указанного выше URI:

http://myhost/api/v2.0/customers
http://myhost/api/v2/customers

Однако вызов любого из URI, перечисленных ниже, приведет к появлению предыдущих версий API:

http://myhost/api/v1/customers
http://myhost/api/v1.7/customers

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

Вывод

Результаты RESTful приводят к тому, что отрасль потребляет оползневое большинство по сравнению с другими конкурентами вместе взятыми. Эта популярность побудила конечные точки RESTful войти и в корпоративную среду. Главное — убедиться, что ваш RESTful API делает все, что должен, следуя рекомендациям, приведенным в этой статье.

Я специально не говорил о безопасности RESTful API, так как это отдельная тема. Возможно, даже тема, о которой я буду говорить в ближайшем будущем.

Хорошего дня!

31
Share: