REST: Представление ресурсов с помощью путей
Представим два ресурса API: каталог и товар. Пусть ресурс каталога представляет собой коллекцию ресурсов товара. Как спроектировать пути этих ресурсов❓
➡️ Путь к ресурсу REST должен быть уникальным.
🔚Чтобы идентифицировать каталог, мы могли бы использовать путь /c.
🔚В случае с товарами мы могли бы использовать ссылку на товар или технический идентификатор и создать с его помощью путь /{productId} (например, /P123). Такие переменные в путях называются параметрами пути.
Пути /c и /{productId} являются совершенно допустимыми путями REST, потому что они уникальны. Но давайте будем откровенны. Что бы вы подумали о таком интерфейсе, если бы увидели его в реальной ситуации❓
➡️ Он не очень удобен для потребителей. Мы всегда должны разрабатывать API для пользователей. Было бы лучше выбрать пути, которые явно указывают, что они обозначают. Почему бы просто не использовать /catalog для ресурса каталога и /product-{productId} для ресурса товара❓ Звучит хорошо, но эти пути не единственная возможность:
🔚/catalog/{productId} - я предмет из каталога
🔚/products/{productId} - я товар из коллекции товаров
➡️ Чтобы повысить удобство использования, связь между ресурсами каталога и товаром можно отобразить в путях наподобие иерархии папок в файловой системе.
🔚Каждый ресурс товара – это элемент в коллекции каталога, идентифицируемый как /catalog, поэтому мы можем выбрать путь /catalog/{productId} для обозначения товара.
🔚Мы также могли бы явно указать, что каталог – это коллекция ресурсов товара, используя путь /products, при этом товар из этой коллекции представлен путем /products/{productId}.
Вариантов много❗️Все они показаны на схеме.
➡️ С точки зрения чистого REST все эти варианты допустимы.
🔚Даже если мы уже отбросили непонятные пути, такие как /c и /{productId}, потому что они явно неудобны для потребителя, у нас все еще есть много возможностей.
🔚Каталог ресурса можно представить как /catalog или /products, а ресурс товара, как /product-{productId}, /catalog/{productId} или /products/{productId}.
Вы можете выбрать любой вариант, какой предпочитаете, но помните, что пути к ресурсам должны быть удобными для пользователя. Пользователи API должны иметь возможность с легкостью расшифровывать их, поэтому чем больше информации вы
предоставите в своих путях, тем лучше❗️
➡️ Хотя официальных правил REST, касающихся проектирования путей к ресурсам (кроме уникальности), не существует, наиболее распространенным форматом является:
🔚/{имя, отражающее тип элемента коллекции во множественном числе}/{идентификатор элемента}
➡️ Использование путей к ресурсам, показывающих иерархию ресурсов, и использование имен во множественном числе для коллекций для отображения типа элемента коллекции стало де-факто стандартом REST. Поэтому в нашем примере каталог должен быть идентифицирован как /products, а товар – как /products/{productId}. Эту структуру можно расширить до нескольких уровней, например: /resources/{resourceId}/sub-resources/{subResourceId}.
#аналитик #навыкАналитика #API #REST #IT
Представим два ресурса API: каталог и товар. Пусть ресурс каталога представляет собой коллекцию ресурсов товара. Как спроектировать пути этих ресурсов❓
➡️ Путь к ресурсу REST должен быть уникальным.
🔚Чтобы идентифицировать каталог, мы могли бы использовать путь /c.
🔚В случае с товарами мы могли бы использовать ссылку на товар или технический идентификатор и создать с его помощью путь /{productId} (например, /P123). Такие переменные в путях называются параметрами пути.
Пути /c и /{productId} являются совершенно допустимыми путями REST, потому что они уникальны. Но давайте будем откровенны. Что бы вы подумали о таком интерфейсе, если бы увидели его в реальной ситуации❓
➡️ Он не очень удобен для потребителей. Мы всегда должны разрабатывать API для пользователей. Было бы лучше выбрать пути, которые явно указывают, что они обозначают. Почему бы просто не использовать /catalog для ресурса каталога и /product-{productId} для ресурса товара❓ Звучит хорошо, но эти пути не единственная возможность:
🔚/catalog/{productId} - я предмет из каталога
🔚/products/{productId} - я товар из коллекции товаров
➡️ Чтобы повысить удобство использования, связь между ресурсами каталога и товаром можно отобразить в путях наподобие иерархии папок в файловой системе.
🔚Каждый ресурс товара – это элемент в коллекции каталога, идентифицируемый как /catalog, поэтому мы можем выбрать путь /catalog/{productId} для обозначения товара.
🔚Мы также могли бы явно указать, что каталог – это коллекция ресурсов товара, используя путь /products, при этом товар из этой коллекции представлен путем /products/{productId}.
Вариантов много❗️Все они показаны на схеме.
➡️ С точки зрения чистого REST все эти варианты допустимы.
🔚Даже если мы уже отбросили непонятные пути, такие как /c и /{productId}, потому что они явно неудобны для потребителя, у нас все еще есть много возможностей.
🔚Каталог ресурса можно представить как /catalog или /products, а ресурс товара, как /product-{productId}, /catalog/{productId} или /products/{productId}.
Вы можете выбрать любой вариант, какой предпочитаете, но помните, что пути к ресурсам должны быть удобными для пользователя. Пользователи API должны иметь возможность с легкостью расшифровывать их, поэтому чем больше информации вы
предоставите в своих путях, тем лучше❗️
➡️ Хотя официальных правил REST, касающихся проектирования путей к ресурсам (кроме уникальности), не существует, наиболее распространенным форматом является:
🔚/{имя, отражающее тип элемента коллекции во множественном числе}/{идентификатор элемента}
➡️ Использование путей к ресурсам, показывающих иерархию ресурсов, и использование имен во множественном числе для коллекций для отображения типа элемента коллекции стало де-факто стандартом REST. Поэтому в нашем примере каталог должен быть идентифицирован как /products, а товар – как /products/{productId}. Эту структуру можно расширить до нескольких уровней, например: /resources/{resourceId}/sub-resources/{subResourceId}.
#аналитик #навыкАналитика #API #REST #IT