Использование @PathParam и @QueryParam: лучшие практики

Быстрый ответ

@QueryParam применим для передачи опциональных параметров, обеспечивающих гибкость при выполнении поисковых запросов, как в случае: ?author=King.

// такой запрос позволит найти книги в жанре триллера, написанные, скажем, Стивеном Кингом
getBooks(@QueryParam("genre") String genre) { ... }

@PathParam используется для обозначения конкретного ресурса в URL, например, /users/112, обеспечивая прямой доступ к нему.

// запрос на дружбу от пользователя! Просмотр профиля пользователя, своего рода стук в конкретную дверь
@Path("/users/{id}") getUser(@PathParam("id") String id) { ... }

Выбирайте @QueryParam для обеспечения гибкости пользователей в фильтрации данных, и @PathParam для указания на конкретный ресурс.

Принятие обоснованного решения: учет необходимостей

Выбор между @QueryParam и @PathParam опирается на специфику информационного запроса к API. Ключевые аспекты для принятия решения:

Важность данных: нужны ли они вовсе?

• Используйте @PathParam для данных, необходимых для идентификации ресурса.
• @QueryParam подходит для тех параметров, которые позволяют настроить результаты поиска.

Иерархия ресурсов

Если важны уникальность ресурса или его позиция в иерархии данных:

// получаем доступ к определённому изданию книги, используя систему классификации Дьюи, как в библиотеке
@Path("/books/{isbn}/editions/{editionId}") 
getEdition(@PathParam("isbn") String isbn, @PathParam("editionId") String editionId) { ... }

Фильтрация, сортировка и постраничный вывод

В таких случаях @QueryParam отлично зарекомендовал себя:

// подскажем библиотекарю, что мы хотим найти произведения Стивена Кинга, выпущенные после 1980 года
@Path("/books")
getBooks(@QueryParam("author") String author, @QueryParam("publishedAfter") Integer year) { ... }

Закладки и кэширование

Неплохо будет использовать @PathParam для действий, которые могут использовать закладки или кэширование:

// профиль пользователя можно добавить в закладки для посещения
@Path("/profiles/{profileId}")
getUserProfile(@PathParam("profileId") String profileId) { ... }

Чистота дизайна API

Разделите пути и параметры URL: @PathParam для прямых путей к ресурсам, @QueryParam для настройки параметров запроса.

@Path("/products/{productId}") 
getProduct(@PathParam("productId") String productId, @QueryParam("reviews") Boolean includeReviews) { ... }

Анализ параметров

Проанализируйте параметр: предназначен ли он для перехода к ресурсу или для настройки запроса?

Упоминание атрибутов

@QueryParam прекрасно подойдет для указания различных атрибутов, когда требуется применить фильтры:

// как детектив на поисках, выясняем, кто работает в отделе продаж и занимает руководящие позиции
@Path("/employees")
searchEmployees(@QueryParam("department") String department, @QueryParam("role") String role) { ... }

Визуализация

Рассмотрим использование @QueryParam и @PathParam на примере системы поиска библиотеки:

Представим библиотеку с двумя различными поисковыми механизмами:

1. **@PathParam**: Система путеводных ориентиров (📚➡️📍)
    – Вас уведомили, что книга лежит в третьем ряду, секция B.
    – Это аналог прямого маршрута к конкретному месту на полке.

2. **@QueryParam**: Справочная служба (🔎💡)
    – Вы определили критерии (например, имя автора), и в ответ получили список подходящих книг.
    – Это выбор книг, соответствующих вашим запросу.

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

визуальная аналогия Path: 🚶‍♂️➡️📚 (Идём непосредственно к цели) Query: 🤔💬🔍📚 (Изучаем и отбираем варианты)

Используйте @PathParam если знаете "адрес", и @QueryParam – если необходима "раскопка" с помощью фильтров.

Научимся у лучших: Анализ успешных паттернов проектирования API

Изучение проверенных REST API поможет сделать обоснованные решения и создать удобный и эффективный API:

Опыт лидеров

API от Github и StackOverflow демонстрируют, как грамотное совмещение параметров пути и запроса приводит к эффективному дизайну API.

Понятность обработчиков URL

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

Доступ к подресурсам

Замена @PathParam незаменима, когда есть необходимость в доступе к конкретному подресурсу:

// Рассматриваем комментарии к определённой записи в блоге
@Path("/blog-posts/{postId}/comments")
getComments(@PathParam("postId") String postId) { ... }

Динамическое содержимое и @QueryParam

@QueryParam подойдет, когда требуется изменить представление страницы или её содержимое, основываясь на предпочтениях пользователя:

// Настраиваем вид панели управления путём выбора виджетов, как будто переставляем мебель в комнате
@Path("/dashboard")
getDashboard(@QueryParam("widgets") List<String> widgets) { ... }

Полезные материалы

1. [RESTful Java with JAX-RS 2.0, 2nd Edition [Книга]](https://www.oreilly.com/library/view/restful-java-with/9781449361433/) — Подробное руководство по использованию аннотаций @PathParam и @QueryParam.
2. Глава 3. JAX-RS Приложение, Ресурсы и Подресурсы — Официальная документация проекта Jersey, содержащая информацию о применении аннотаций @PathParam и @QueryParam.
3. PathParam (Java(TM) EE 7 Specification APIs) — Детальный обзор аннотации @PathParam от Oracle.
4. QueryParam (Java(TM) EE 7 Specification APIs) — Подробное описание аннотации @QueryParam от Oracle.
5. Правила именования URL и лучшие практики в REST API — Лучшие методики именования URI в REST API, включая параметры запроса и пути.
6. Статья на Medium: Проектирование параметров REST API — Обобщающий материал по применению аннотаций @PathParam и @QueryParam.