Где в get запросе передать входные параметры
Перейти к содержимому

Где в get запросе передать входные параметры

  • автор:

Шаг 3 «Параметры (Описание API)»

Параметрами являются опции, которые можно передать конечной точке (например, указать формат ответа или возвращаемую сумму), чтобы повлиять на ответ. Существует четыре типа параметров:

  • параметры заголовка,
  • параметры path,
  • параметры строки запроса,
  • параметры тела запроса.

Различные типы параметров часто документируются в отдельных группах на одной странице. Не все конечные точки могут содержать каждый тип параметра.

Примеры параметров

Скриншот ниже является примером раздела параметров с Box API:

boxApiParam

В этом примере параметры сгруппированы по типу:

  • параметры path,
  • параметры запроса,
  • параметры тела.

Конечная точка также выделяет параметр path collab_id распознаваемым образом в определении конечной точки.

Часто параметры просто перечислены в таблице или списке определений, как в этом примере:

Параметр Обязательно/Опционально Тип данных
format Optional String

Вот пример документации API Yelp

search API

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

Четыре типа параметров

REST API обладают 4 типами параметров:

  • Параметры заголовка: параметры, включенные в заголовок запроса, обычно относятся к авторизации.
  • Параметры path: Параметры в пределах path конечной точки перед строкой запроса, отделяются знаком ? . Обычно эти параметры выделяются фигурными скобками.
  • Параметры строки запроса: Параметры в строке запроса конечной точки, располагаются после знака ? .
  • Параметры тела запроса: Параметры, включенные в тело запроса. Обычно в формате JSON.

Tip: Термины для каждого из этих типов параметров взяты из спецификации OpenAPI, которая определяет формальную спецификацию, которая включает описания каждого типа параметра (см. Шаг 4 Объект paths ). Использование терминологии промышленного стандарта поможет разработать словарь элементов API для их описания.

Что следует отметить в документировании параметров

Независимо от типа параметра, определите следующее для каждого параметра:

Типы данных параметров

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

Вот типы данных наиболее распространенные в REST API:

  • string: буквенно-цифровая последовательность букв и / или цифр;
  • integer: целое число — может быть положительным или отрицательным;
  • boolean: true или false значение;
  • object: пара ключ-значение в формате JSON
  • array: массив значений

Note: В программировании намного больше типов данных, и если имеются более конкретные типы данных, которые важно отметить, обязательно нужно их документировать. Например, в Java важно отметить допустимый тип данных, поскольку Java выделяет пространство памяти в зависимости от размера данных. Таким образом, Java получает гораздо более конкретную информацию о размере чисел. Есть byre, short, int, double, long, float, char, boolean и так далее. Однако, обычно, в REST API такой уровень детализации не нужно указывать.

Максимальное и минимальное значения параметров

Помимо указания типа данных, параметры должны указывать максимальные, минимальные и допустимые значения. Например, если API сервиса погоды допускает только координаты долготы и широты конкретных стран, эти ограничения должны быть описаны в документации в разделе параметров.

Пропуск информации о максимальных / минимальных значениях или других недопустимых значениях является распространенной ошибкой в ​​документации. Разработчики часто не осознают всех «творческих» способов, которыми пользователи могут использовать API. Команда тестирования или обеспечения качества (QA), вероятно, является лучшим ресурсом для определения значений, которые не должны допускаться, потому что задача QA — попытаться взломать API.

Tip: При тестировании API, можно попробовать запустить конечную точку без обязательных параметров, либо с неправильными параметрами, либо со значениями, которые превышают максимальные или минимальные значения. Изучить ответ об ошибке, который возвращается. Включить этот ответ в раздел статусы и коды ошибок. О важности тестирования узнаем больше в модуле Тестирование документации.

Параметры заголовка

Параметры заголовка включаются в заголовок запроса. Обычно заголовок включает в себя только параметры авторизации, которые являются общими для всех конечных точек; в результате параметры заголовка обычно не документируются для каждой конечной точке. Детали авторизации в параметрах заголовка документированы в разделе Аутентификация и авторизация.

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

Параметры path

Параметры path являются частью конечной точки. Например, в следующей конечной точке и являются обязательными параметрами path:

/service/myresource/user//bicycles/

Параметры path обычно устанавливаются с помощью фигурных скобок. Но в некоторых API документациях стили прописывают перед значением двоеточие или используют вообще иной синтаксис. При документировании параметров path указываются значения по умолчанию, допустимые значения и другие сведения.

Цветовая кодировка параметра path

При перечислении параметров path в конечной точке, может помочь цветовое кодирование параметров, для их легкой идентификации. Цветовое выделение параметров дает понять, что является параметром path, а что нет. Посредством цвета мы создаем непосредственную связь между конечной точкой и определениями параметров.

Например, если выделить цветом параметры и в конечной точке:

/service/myresource/user//bicycles/

То позже можно использовать этот же цвет при описании этих же параметров.

Параметр URL Описание параметра
user Описание параметра user
bicycleId Описание параметра bicycleId

Использование цвета для выделения параметров позволяет легко выделить определяемый параметр и его связь с определением конечной точки.

Параметры строки запроса

Параметры строки запроса указываются после знака вопроса ? В конечной точке. Знак вопроса, параметры, которые следуют за ним и их значения, называется «строкой запроса». В строке запроса каждый параметр перечисляется один за другим с амперсандом & , разделяющим их. Порядок параметров строки запроса не имеет значения.

Эта строка запроса:

/surfreport/?days=3&units=metric&time=1400 
/surfreport/?time=1400&units=metric&days=3 

вернут один и тот же результат.

Однако в параметрах path порядок имеет значение. Если параметр является частью фактической конечной точки (не добавляется после строки запроса), это значение обычно описывается в описании самой конечной точки.

Параметры тела запроса

Часто с запросами POST (где мы что-то создаем) мы отправляем объект JSON в теле запроса. Этот параметр и есть тело запроса. Обычно форматом тела запроса является JSON. Этот JSON объект может быть длинным списком пар ключ-значение с несколькими уровнями вложенности.

Например, конечной точкой может быть что-то простое, например /surfreport/ . Но в тело запроса мы можем включить объект JSON со многими парами ключ-значение, например:

 "days": 2, "units": "imperial", "time": 1433524597 > 

Документирование параметров тела сложного запроса

Документирование данных JSON (как в параметрах тела запроса, так и в ответах) является одной из самых сложных частей документации API. Документирование JSON объекта будет легким, если этот объект прост, с несколькими парами ключ-значение на одном уровне. Но если у нас есть JSON объект с несколькими объектами внутри объектов, множественными уровнями вложенности и большими объемными данными, это может быть сложно. И если объект JSON занимает более 100 строк, или 1000, нам необходимо тщательно продумать, как представить информацию.

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

Безусловно, если объект JSON относительно мал, таблица, вероятно, является лучшим вариантом. Но есть и другие дизайнерские подходы.

Взгляните на ресурс eBay findItemsByProduct. Вот параметр тела запроса (в данном случае формат XML):

eBay

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

eBay table

Но пример запроса также содержит ссылки на каждый из параметров. При клике на значение параметра в примере запроса, мы переходим на страницу, которая предоставляет более подробную информацию о значении этого параметра, например ItemFilter . Отдельная страница с более подробной информацией лучше и удобнее, потому что значения параметров являются более сложными и требуют подробного объяснения.

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

Подход Swagger к параметрам тела запроса

Пользовательский интерфейс Swagger, который мы рассмотрим позже, а также его демо, предоставляет другой подход к документированию параметра тела запроса. Swagger UI показывает параметры тела запроса в формате, который вы видите ниже. Интерфейс Swagger позволяет переключаться между представлением «Пример значения» и представлением «Модель» для ответов и параметров тела запроса.

Swagger

Посмотрим на Swagger Petstore для изучения. “Пример значения” показывает образец синтаксиса вместе с примерами. При нажатии на ссылку “Модель””, видим пример параметра тела запроса и описания каждого элемента.

Модель включает в себя переключатели «развернуть / свернуть» со значениями. (Демо Petstore не имеет множество описаний параметров в модели, но если включить описания, они будут отображаться в модели, а не в примере значения.)

Tip: Мы познакомимся с Swagger более подробно в разделе Знакомство со спецификациями OpenAPI и Swagger. А пока сосредоточимся на этих основных элементах справочной документации API. Мы увидим, что эти же разделы появляются в спецификации OpenAPI.

Можно заметить, что существует множество вариантов документирования JSON и XML в параметрах тела запроса. Правильного способа документировать информацию нет. Как всегда, выбираем метод, который отображает параметры нашего API наиболее простым и легким для чтения способом.

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

Параметры конечной точки SurfReport

Давайте посмотрим доступные параметры и создадим таблицу с описанием параметров для нашего нового ресурса surfreport. Вот пример, как может выглядеть информация о параметрах:

Параметры

Параметры path
Параметр path Описание
Относится к идентификатору пляжа, который вы хотите посмотреть. Все коды beachId доступны на нашем сайте sampleurl.com.

Параметры строки запроса

Параметр строки запроса Обязательно/ необязательно Описание Тип данных
days Optional Количество дней, включаемых в ответ. По умолчанию = 3 Integer
time Optional При указании времени в ответе будет выводиться только указанный час Integer. Unix format (ms since 1970) UTC

Tip: Если использовать Markdown для документации, можно рассмотреть возможность использования синтаксиса HTML для создания таблиц. HTML позволяет задавать ширину столбцов. У Markdown нет такой возможности. В HTML можно использовать свойство colgroup , чтобы указать col width (ширину) столбца для каждого столбца.

Следующие шаги

После того, как мы задокументировали параметры пора посмотреть на Пример запроса к ресурсу

Как для GET метода передать кастомный тип объекта во входных параметрах?

Веб-сервис.
Как для GET метода передать кастомный тип объекта во входных параметрах?

Есть тип:
[DataContract]
public class SomeType [DataMember]
public string path < get; set; >
[DataMember]
public string als < get; set; >
>

[OperationContract]
[WebInvoke(Method = «GET»,
RequestFormat = WebMessageFormat.Json,
BodyStyle = WebMessageBodyStyle.Wrapped,
ResponseFormat = WebMessageFormat.Json,
UriTemplate = «/ping/»)]
[return: MessageParameter(Name = «data»)]
public object Pong(string s, SomeType SomeData) return JsonConvert.SerializeObject(SomeData);
>

При попытке отправить гет запрос через постман и передать данные, получаем всегда ответ:

Что по факту равно если вообще не передавать параметр.

Но если мы делаем метод POST и передаем в теле этот же параметр вот так:

То работает, чего я не понимаю?

5 комментариев
2 апреля 2022 20:10

Я не помню, что бы в get запросе можно было передавать тело запроса анонимно, для такого метод post предназначен, а get данные через параметры в url всегда передаются.
можно попробовать принять json из урла , сделав так, но это уже извращение
`?someBody=`?

2 апреля 2022 23:27

Dima Avdoshin,

тело запроса это же просто данные, какая разница что передавать данные если их конечно не много через гет или через пост? особенно если ты хочешь только читать данные

2 апреля 2022 23:35

Dima Avdoshin,

вопрос в тому как передать в гет запросе данные так что бы это потому преобразовалось в объект, потому как с List передается и все норм, я вот думаю в чем разница между Guid и моими типами? скрин приложу как передаю

3 апреля 2022 13:57

Стас Гаврилюк,

к сожалению я не смог сделать так как ты, вероятно может получится с помощью класса обертки (код ниже), где в knowType указываются все возвращаемые типы, можешь назвать его как указано ниже

[DataContract] [KnownType(typeof(OpenIdStatus))] [KnownType(typeof(string))] public class ReturnValue  [DataMember] public object Value  get; set; > >

также для меня работало следующее
/ping/12?someObj=''
тоже самое и с обжектом работает

[OperationContract] [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped, ResponseFormat = WebMessageFormat.Json, UriTemplate = "/ping/?someObj=")] [return: MessageParameter(Name = "data")] public dynamic Pong(string s, dynamic SomeData)  return JsonConvert.DeserializeObject(SomeData); >

параметр ввиде объекта определенного типа не принимает , не смог нагуглить почему, пишет , что

>Операция "Pong" в контракте "WebService1C" содержит переменную запроса с именем

"SomeData" и типом "Terrasoft.Configuration.SomeType", но тип

"Terrasoft.Configuration.SomeType" не является преобразуемым посредством

"QueryStringConverter". Переменные для переменных запроса UriTemplate должны иметь типы, которые могут

преобразовываться при помощи "QueryStringConverter".

Laravel по-русски

Русское сообщество разработки на PHP-фреймворке Laravel.

Страницы 1

#1 26.02.2016 10:50:15

MadHatter +2 Сообщений: 112

Request и GET запрос

Здравствуйте. Нуждаюсь в небольшом ликбезе. Пытаюсь методом GET передать в контроллер параметр, например id. В контроллере принимаю таким образом:
public function getId(Request $request) dd($request->id);//Выводится нужный id
dd($request->all());//Выводится массив, но в нем нет id
>
Далее мне нужно передать $request в Validator. Почему метод all() не возвращает id? И как мне его отправить в Validator?

Не в сети 24.12.2015

#2 26.02.2016 11:40:39

duster +4 Откуда: Мельбурн Сообщений: 148

Re: Request и GET запрос

Покажите route? Каким образом ID передается — как query параметр, или как часть URL?

Валидировать самый простой способ — сделать кастомный запрос php artisan make:request, заменить Request $request на этот новый класс, а там внутри класса Вам Laravel создаст метод rules() — там будут правила для валидатора

Не в сети 13.01.2016

#3 26.02.2016 11:48:52

MadHatter +2 Сообщений: 112

Re: Request и GET запрос

Route::get('/admin/toBasket/', 'AdminController@toBasket')->where('id', '[0-9]+');
Да, передается как часть урла.

Не в сети 24.12.2015

#4 26.02.2016 23:28:58

MadHatter +2 Сообщений: 112

Re: Request и GET запрос

Не в сети 24.12.2015

#5 27.02.2016 02:41:18

duster +4 Откуда: Мельбурн Сообщений: 148

Re: Request и GET запрос

Так и думал — у Вас же ID в URL, не в параметрах.

Входные параметры (массив $request->all()) по определению — это GET/POST параметры (то что идет после? в адресе).

Параметр, замаскированный в URL — это не параметр GET, строго говоря.

Laravel такие значения вставляет в объект $request (что Вы уже и так нашли), еще они доступны как $request->route(’id’).

Валидировать можно в методе authorize() в созданном классе запроса. Можно сделать проверку is_int(), можно проверить есть ли права у юзера.

☺

’required’ — бессмысленно проверять, раз юзер сюда попал по маршруту — значит ID указан. Иначе бы не сработал маршрут

Не в сети 13.01.2016

#6 27.02.2016 03:31:52

MadHatter +2 Сообщений: 112

Re: Request и GET запрос

duster пишет:

'required' - бессмысленно проверять, раз юзер сюда попал по маршруту - значит ID указан. Иначе бы не сработал маршрут

Точно) И на numeric тоже, ведь в роуте прописан where)
А каким образом в методе Authorize мне получить данную переменную, чтобы проверить на is_int()?

Не в сети 24.12.2015

#7 27.02.2016 06:09:48

duster +4 Откуда: Мельбурн Сообщений: 148

Re: Request и GET запрос

Я же написал — два способа:

if (is_int($request->id)) <> или if (is_int($request->route(’id’))) <>

Первый способ — это magic property, второй более «точный»

☺

Только получается что проверять то и не надо — маршрутизатор уже проверил Можно проверить — существующий ли ID, есть ли доступ на него и тд

Не в сети 13.01.2016

#8 27.02.2016 07:41:25

MadHatter +2 Сообщений: 112

Re: Request и GET запрос

Ясно, спасибо больое, вы мне очень помогли)

Обязательный входной параметр в get-запросе. Как правильно записать, если нужна фильтрация внутри кода по айди? Dart

С третьим пунктом как раз и есть проблема. По АПИ требуется обязательный входной параметр в get-запрос. Как правильно его оформить?

Я делаю сейчас так: Здесь mv_id - это обязательный входной параметр, но когда я делаю вот так:

http://mylink/getRaceList.php?fmt=json&mv_id - выдает ошибку

Но когда ввожу так, то все работает: http://mylink/getRaceList.php?fmt=json&mv_id=1

Но мне нужен список отфильтрованного маршрута, а не только первый. Как правильно задать параметр?

Пишу на Dart'е, пробовал объединять модели, но это не срабатывало, сейчас пытаюсь фильтровать при помощи where метода, но фильтрация работает, если нет обязательного входного параметра.

Модели про которые говорю:

class ScheduleVariants < int mvId; int mrId; String mvDesc; DateTime mvStartdate; DateTime mvEnddate; >class RaceCard

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *