Параметры запросов: JSON, формы, типы и заголовки

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

Выбор формата тела

• JSON подходит для обычных именованных параметров, вложенных данных и массивов. Передавайте объект в кодировке UTF-8 с Content-Type: application/json.
• Обычная URL-форма передаёт текстовые поля без файла: например, id=900101&page=1. Её тип содержимого: application/x-www-form-urlencoded.
• Multipart-форма передаёт файл и текстовые поля одним запросом. При использовании FormData не задавайте Content-Type вручную: HTTP-библиотека сформирует его вместе с границей частей boundary. Имя файлового поля и допустимые форматы зависят от метода. Подробнее: «Загрузка файлов и вложений».

Не дублируйте одно поле в нескольких источниках. Для обычных прикладных параметров сначала читается тело, затем URL, затем поля POST-формы. Более поздний источник заменяет прежнее одноимённое значение. Это особенно важно, если адрес с ?id=... используется вместе с JSON-телом.

Заголовки запроса

Служебные заголовки обрабатываются отдельно от прикладных полей. Значения lang, out или auth внутри JSON не настраивают язык, формат ответа и авторизацию. Передавайте их предусмотренными заголовками. Не помещайте пароль или токен в URL.

Примеры JSON и обычной формы

В примерах метод laboratory/measuring/place/info получает периоды местонахождения средства измерения. Поле id означает ID экземпляра, page задаёт страницу списка. Адрес, токен и номер условные; замените их своими значениями.

Передача тех же полей JSON-объектом:

curl 'https://lab.example/api/laboratory/measuring/place/info' \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Lang: ru' \
  -H 'Out: json' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --data '{"id":900101,"page":1}'

Передача обычной URL-формой. Здесь curl сам задаёт нужный тип содержимого и кодирует значения:

curl 'https://lab.example/api/laboratory/measuring/place/info' \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Lang: ru' \
  -H 'Out: json' \
  --data-urlencode 'id=900101' \
  --data-urlencode 'page=1'

В обоих случаях отправляется POST. Не переносите поля этого примера в другой метод без его описания: одноимённый параметр может иметь другое назначение.

Как меняются типы значений

Ядро рекурсивно преобразует значения. Кавычки JSON не гарантируют, что строка останется строкой после входа:

Для строкового idnum предусмотрено исключение: {"idnum":"0123.330"} сохраняет номер текстом. Оно действует также для val рядом с field="idnum", включая групповые данные. Если передать {"idnum":123.330} числом, исключение не восстановит исходное написание.

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

Вложенные и пустые значения

Если метод принимает вложенные поля и массивы, передавайте их структурами JSON. Например:

{"data":{"item":"text"},"ids":[2,3]}

Соответствующая форма использует имена data[item] и повторные ids[]. Это пример построения структуры, а не набор полей, обязательный для всех методов. Строка с текстом JSON внутри поля сама не превращается во вложенный объект: её должен отдельно разбирать обработчик.

Общий разбор не сохраняет различие между пустыми {} и []: оба становятся PHP-массивами. Отсутствие поля, пустая строка, ноль, false и null могут обрабатываться методом по-разному. Не используйте случайное пустое значение как универсальную команду удаления или очистки.

Текст, XML и файлы

В обычных строках убираются крайние пробелы, а символы < и > заменяются на ‹ и ›. Поэтому обычный JSON-запрос не подходит для передачи произвольного HTML/XML с ожиданием побайтного сохранения текста.

Сырые XML-тела и двоичные части обмена используйте только там, где это предусмотрено конкретным интерфейсом. Они не создают универсальный XML-импорт или загрузку файла в любой метод API. Для обычного вложения используйте multipart-метод с нужным файловым полем.

Ответ и ошибки запроса

Синтаксически правильное тело не подтверждает правильность даты, телефона, диапазона или допустимость операции. Эти правила проверяет целевой метод. Результат оценивайте по его ответу: какой объект обработан и какое значение возвращено.

При 400 проверьте синтаксис JSON, кодировку UTF-8, форму тела и обязательные поля. Для именованных параметров отправляйте JSON-объект, а не отдельное число, логическое значение или строку. Заголовок Content-Type не исправляет содержимое тела. Формат ошибок описан в статье «Ответы API и обработка ошибок».

Для номера с ведущими нулями или другого кода с важным написанием сначала проверьте один пример и сравните возвращённое значение с исходным. Это помогает заметить преобразование до массовой передачи данных.

Продолжение настройки

Выбор адреса сервера и первого метода описан в статье «API TesLab: адрес сервера и первый запрос».