Создание REST API: как определить, какие параметры go для заголовков, тела, URL или запроса? - PullRequest
0 голосов
/ 09 апреля 2020

Как вы решаете, где параметры go? Предположим, что API предназначен для объекта, который имеет идентификатор, несколько полей, и каждый запрос может иметь или не иметь токен. Для объекта должны быть запросы GET, PUT, POST и DELETE.

1 Ответ

1 голос
/ 09 апреля 2020

Как правило, вы хотите, чтобы все параметры, необходимые для идентификации ресурса, были непосредственно закодированы в URI где-то . Это позволяет вам пометить URI для последующего использования и поделиться этой закладкой с другим человеком / процессом.

Пример:

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

Так, где в URI информация go?

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

Компонент идентификатора фрагмента URI позволяет косвенно идентифицировать вторичный ресурс посредством ссылки на первичный ресурс и дополнительную идентифицирующую информацию.

В Интернете фрагменты были полезны, поскольку они позволяли вам обращаться к пользовательскому агенту, чтобы сосредоточиться на конкретном элементе в представлении. Фрагмент не отправляется по сети, а используется только на стороне клиента. Представьте себе Data Transfer Object - один большой кешируемый документ (поэтому нам не нужно много циклов), с большим количеством URI, которые указывают на указанную c информацию в нем.

Other параметры могут быть закодированы в сегменты пути или строку запроса. Машинам все равно (20 лет go, это было несколько менее верно - нам иногда приходилось обходиться кэшем, который неправильно обрабатывал часть запроса URI).

URI с параметры, настроенные с помощью application/x-www-form-urlencoded строк запроса, были удобны в Интернете, поскольку HTML имел поддержку формы для создания этих идентификаторов на клиенте.

В наши дни мы можем использовать шаблоны URI для описания как вычислить новый URI, который дает вам больше возможностей.

Относительное разрешение дает нам механизм общего назначения для вычисления нового URI из заданного ссылочного идентификатора. Подумайте о точечных ссылках с символическими c ссылками. Этот механизм в основном основан на навигации по иерархической части URI, то есть путь .

Машины не заботятся об иерархии ресурсов, и иерархия идентификаторов параллель

# Here's an identifier for a collection
/collection
# Here's an identifier for a member of this collection
/collection/member

# Here's an identifier for a collection
/2c957fb6-ac92-4fdb-a086-02292c3b7c7c
# Here's an identifier for a member of this collection
/41d36a69-d10c-4503-8e5e-3b2d64e9c3a6

Все эти образцы отлично , что касается машин; но людям легче работать с верхним набором.

Заголовки - это метаданные, относящиеся к области «переноса документов по сети».

Тело - это сам документ - это сообщение, которое передается по сети (в некотором смысле запрос http и заголовки - это envelope , который несет сообщение). Да, это иногда означает, что информация, содержащаяся в сообщении, также копируется в заголовки или через шаблон в target-uri.

...