php получение post запроса json

Как отправить JSON-данные на сервер

Первый шаг на пути к облачному хранению данных.

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

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

Как это устроено

Если мы хотим хранить данные на сервере и отправлять их туда в любой момент, нам нужно действовать так:

Первые три пункта сделаем на клиенте — нашей HTML-странице, а скрипт и настройки — на сервере. Скрипт будем писать на PHP, поэтому, если не знаете, что это и как с этим работать, — почитайте.

Чтобы было проще, мы отправим и обработаем на сервере совсем маленький JSON — в нём всего две пары «имя: значение», но даже со сложным запросом всё будет работать так же.

Готовим HTML-страницу

У нас будет очень простая страница, потому что самое важное сейчас — научиться работать с JSON-форматом, а красоту наведём позже.

На странице нам понадобятся:

Мы сразу подключим jQuery, чтобы в скрипте напрямую обращаться к полям ввода и месту для вывода результата. А ещё заранее зададим синий цвет для вывода ответа от сервера — так мы сразу отличим данные на странице от того, что нам ответил сервер.

На языке HTML это будет так:

php получение post запроса json. Смотреть фото php получение post запроса json. Смотреть картинку php получение post запроса json. Картинка про php получение post запроса json. Фото php получение post запроса jsonВнешний вид очень простой, чтобы проверить работоспособность всей системы

Отправляем данные на сервер

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

К счастью, инженеры давно придумали, как отправлять данные на сервер, не перезагружая страницу. Для этого используют JavaScript.

// создаём новый экземпляр запроса XHR

Для запроса нам нужно знать адрес, куда будем отправлять наш JSON — это и есть адрес нашего скрипта, который мы напишем позже. Мы будем писать его на PHP, поэтому заранее можем придумать ему имя и адрес, где он будет лежать: http://mihailmaximov.ru/projects/json/json.php.

// адрес, куда мы отправим нашу JSON-строку

Когда мы знаем адрес, мы можем открыть соединение, чтобы сервер был готов принять наши данные. Это значит, что мы пока ничего ценного туда не посылаем, а просто предупреждаем сервер, что скоро что-то прилетит:

// открываем соединение. url — это переменная с нашим адресом

Теперь напишем заголовок запроса, чтобы сервер понимал, какие данные мы ему пришлём и как ему их обрабатывать. Так как у нас JSON, то это и пропишем в заголовке:

// устанавливаем заголовок —
выбираем тип контента, который отправится на сервер,
в нашем случае мы явно пишем, что это JSON

Чуть ниже сразу пропишем поведение скрипта на случай ответа сервера. Сервер должен обработать наши данные, вернуть ответ, а мы должны этот ответ поймать и вывести на страницу:

Последнее, что нам осталось сделать, — вытащить наши введённые данные из полей, собрать из них JSON и отправить на сервер:

// преобразуем наши данные JSON в строку

Пишем PHP-скрипт для сервера

Задача скрипта пока будет очень простой — ему нужно будет получить наши данные и показать, что всё пришло как нужно. В PHP уже встроена команда, которая разбирает JSON-строку на составляющие, поэтому весь скрипт будет занимать три строчки:

Сам код нам нужно сохранить как json.php и положить в папку /projects/json/ на нашем сайте — так мы прописали в скрипте на JavaScript.

Настраиваем сервер

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

php получение post запроса json. Смотреть фото php получение post запроса json. Смотреть картинку php получение post запроса json. Картинка про php получение post запроса json. Фото php получение post запроса json

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

Header set Access-Control-Allow-Origin «*»

Первая строка разрешает серверу работать с запросами от любых страниц (хоть это и небезопасно, но пока мы учимся — так можно). Вторая строка содержит список разрешённых запросов. Третья разрешает нужные нам заголовки в запросе.

Фактически этот файл сейчас означает: «разрешаю тебе принимать запросы со всех сайтов, вот такого типа запросы можно принимать, вот такие у них могут быть заголовки». В буквальном смысле методичка.

Откуда вы знаете, что нужны именно эти команды?

Когда мы писали эту статью, нам потребовалось почитать справочники и форумы, протестировать несколько вариантов команд и в итоге найти именно эту — ту, что работает.

Вся информация по командам и настройке в интернете уже есть. Нужно просто ее искать, анализировать и тестировать.

Теперь в интернете есть ещё и эта статья, которая поможет вам меньше искать 🙂

Перезапускаем нашу локальную страничку и пробуем её в действии.

php получение post запроса json. Смотреть фото php получение post запроса json. Смотреть картинку php получение post запроса json. Картинка про php получение post запроса json. Фото php получение post запроса jsonВсё работает. Синий текст мы получили от PHP-скрипта на сервере. Связь налажена!

Что дальше

Мы научились отправлять данные на сервер и немного работать там с ними. Дальше попробуем заменить в наших проектах локальное хранение данных на хранение на сервере, чтобы проекты работали с любого браузера.

Источник

cURL в PHP: примеры POST, GET запросов с headers, cookie, JSON и многопоточностью

В этой статье мы рассмотрим эффективные приемы работы с cURL, отправление POST, GET и т.д. запросов, работу с cookie, заголовки, JSON а также в конце статьи будут некоторые полезные инструменты, которые могут значительно облегчить вам работу с HTTP запросами.

GET запрос при помощи cURL

Для того, чтобы отправить запрос, нужно создать объект при помощи функции curl_init(), а затем следует настроить его.

Все настройки, которые вы можете найти по этой ссылке. Там вы найдете опции, которые мы будем устанавливать функцией curl_setopt, в дальнейших примерах.

Пример простого GET запроса при помощи cURL:

Если в результате сервер вернет нам редирект, то мы по нему автоматически не перейдем. А иногда это бывает полезно. Чтобы cURL автоматически шел по редиректу нужно установить опцию CURLOPT_FOLLOWLOCATION.

С установленной опцией скрипт автоматически перейдет по вернувшемуся редиректу и вернет ответ уже с итоговой страницы.

POST запрос при помощи cURL

Теперь давайте отправим post запрос на адрес https://httpbin.org/anything

Отлично, с GET и POST запросами в cURL мы немного освоились. Теперь разберемся с заголовками, которые мы можем отсылать в запросе.

Заголовки устанавливаются при помощи опции CURLOPT_HTTPHEADER Чтобы получше узнать, для чего нужна эта опция давайте попробуем отправить POST запрос в формате JSON

cURL: POST запрос в формате JSON

Отличия конфигурации JSON запроса от обычного POST запроса заключается в том, что мы кодируем поля при помощи json_encode() И добавляем заголовок Content-Type: application/json

cURL: GET запрос в формате JSON

GET запрос в формате JSON отправляется так же как и POST запрос, просто нужно CURLOPT_CUSTOMREQUEST установить в ‘GET’

cURL и другие виды HTTP запросов: PUT, DELETE, HEAD, PATCH, OPTIONS, CONNECT и т.д.

Стоп, Дмитрий, прекрати выдумывать виды запросов!

Ничего я не выдумываю: HTTP протокол предполагает множество типов HTTP запросов просто POST и GET являются более распространенными.

Чтобы отправить PUT запрос, нужно установить опцию CURLOPT_PUT таким образом:

Это делается по тому же принципу, как и CURLOPT_POST. Но что делать с остальным зоопарком запросов? Разве у cURL есть CURLOPT_DELETE или CURLOPT_HEAD? Нет.

Для того, чтобы отправлять другие виды запросов есть другая опция: CURLOPT_CUSTOMREQUEST

Вместо строки curl_setopt($curl, CURLOPT_POST, true); мы явно задаем имя запроса опцией CURLOPT_CUSTOMREQUEST:

Замечание: Не используйте эту возможность пока не убедитесь, что сервер поддерживает данный тип запроса.

Как получить заголовки ответа

В предыдущем примере мы научились посылать заголовки. Самый правильный способ принять заголовки:

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

Рассмотрим такой пример:

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

Скачивание больших файлов с помощью cURL

Для того, чтобы скачать большой файл пригодится этот способ:

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

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

Параллельные cURL запросы в PHP

Для чего могут потребоваться многопоточные запросы? Например у нас есть много URL адресов:

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

Как выполнить 3 запроса одновременно? В этом нам поможет curl_multi_

Давайте решим конкретную задачу при помощи параллельных curl запросов. Нам нужно отправить одновременно 3 запроса.

Такие параллельные запросы выполняются значительно быстрее чем поочередные.

cURL запросы с сохранением и загрузкой cookie из файла

cURL позволяет нам установить cookie при передачи запросов, а также автоматически принимать и устанавливать cookie, которые нам возвращает сервер, сохраняя их между запросами.

Давайте рассмотрим такой пример:

Теперь cookie у нас хранятся в файле cookie.txt в директории со скриптом (если вы ничего не меняли). Если мы совершаем повторные запросы, то cURL автоматически берет и отправляет cookie на сервер, как и обычный браузер. Таким образом мы можем авторизироваться на сайте и сохранить сеанс между запросами.

Передача cookie без файлов

Иммитация браузера с помощью cURL

Иногда сайт, к которому мы обращаемся может фильтровать запросы, защищаясь от парсинга. Если для этого используются упрощенные способы защиты, например проверка User-Agent, то мы можем легко притвориться, что являемся реальным польователем, который взаимодействует с сайтом через браузер, мы можем послать заголовки и cookie, которые обычно посылает браузер.

В данном примере установлены заголовки, которые посылает Chrome.

В простых ситуациях этого хватает. Но если используется защита при помощи javascript или что-то более продвинутое, то здесь cURL бессилен, и следует использовать либо BAS либо Zennoposter. Либо если вы хотите попытать счастье с PHP, то Selenium.

Не используйте эти знания в противоправных целях.

cURL запросы через прокси

Простой пример для отправки запросов через proxy. Если ваш прокси предполагает авторизацию, то раскомментируйте соответствующие строчки.

Отправка файлов

Авторизация с помощью cURL

HTTP Авторизация

Чтобы с помощью cURL авторизироваться на сайте, который использует Basic HTTP-аутентификацию нужно установить опцию CURLOPT_USERPWD, в которой будет наш логин и пароль.

OAuth авторизация

Авторизация через форму

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

Допустим на сайте есть такая форма:

Тогда наш cURL запрос должен быть сформирован так:

Автоматическое построение запросов

Перевод консольной команды curl в PHP

И вот еще один сервис, который переводит консольную команду curl в PHP: https://incarnate.github.io/curl-to-php/

Так вы можете создать простые запросы на cURL в PHP не создавая их вручную.

Лайфхак

В консоли браузера, во вкладке сеть, вы можете кликнуть правой кнопкой мыши и скопировать любой запрос в виде команды cURL, а потом с помощью сервиса curl-to-php перевести запрос в PHP. Теперь вы вообще можете сконвертировать в cURL абсолютно любой запрос, который посылает ваш браузер.

Как работать с cURL гораздо проще

Вы можете спросить: почему у cURL такие кривые и страшные методы? У вас может возникнуть желание взять и создать обертку для работы с cURL, чтобы вы могли не писать каждый раз большие куски некрасивого кода, а писать все проще, например так:

К счастью, такая обертка уже написана и найти ее можно здесь: https://github.com/php-curl-class/php-curl-class

Просто установите ее при помощи: composer require php-curl-class/php-curl-class и не работайте с кривыми кусками кода, которые таковы вероятно потому, что cURL изначально консольное приложение.

POST и GET запросы без cURL

С помощью PHP мы можем отправить простой GET запрос используя функцию file_get_contents.

При помощи file_get_contents мы также можем отправить POST запрос.

Подробнее о том, какие опции можно передавать в stream_context_create, вы можете изучить здесь: http://docs.php.net/manual/ru/context.http.php

Другие инструменты для работы с запросами в PHP

Для работы с запросами есть еще более мощный инструмент: Guzzle

Несколько примеров на Guzzle

GET запросы на Guzzle

Разные типы запросов на Guzzle

Асинхронные запросы на Guzzle

Если интересно, то читайте: Guzzle Quick Start

Пишите комментарии, если что-то осталось непонятно.

Источник

PHP и формат передачи данных JSON

JSON (JavaScript Object Notation) – формат для обмена данными в текстовом виде. Позволяющий передавать сложные структуры данных в сериализованном виде. Этот формат передачи данных стал настолько популярен, что уже в ядро PHP начиная с версии 5.2.0, были добавлены функции по обработке данных в этом формате. А это значит, что нет необходимости в подключении дополнительных расширений. Формат данных JSON хорошо понятен человеку. Кроме того данный тип обмена данными широко используется между различными API сервисами. А при корректной разработке алгоритмов для обмена информацией, можно получить очень высокий прирост скорости чем, к примеру, при работе с данными в формате XML.

Отправка данных

Отправить данные в формате JSON можно двумя способами: сформировать GET или POST запрос с закодированными данными расположенными в GET или POST переменной или же поместить данные в тело документа. На практике обычно используется второй вариант.

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

В качестве параметра value указываются данные которые требуется закодировать. Поддерживается любой тип кроме типа resource. Параметр options содержит битовую маску из возможных предоставленных значений (см. таблицу с предоставленными JSON константами).

Использование этой функции позволяет получить содержимое файла в виде строки. Параметр filename это имя считываемого файла. В параметре use_include_path начиная с версии PHP 5 можно использовать константу FILE_USE_INCLUDE_PATH для поиска файла в include path. Параметр context представляет ресурс контекста, созданный с помощью функции stream_context_create(). В случае неудавшейся попытки открытия файла, будет возвращено значение false. Параметр offset содержит смещение с которого начнется чтение данных. В параметре maxlen указывается размер получаемых данных.

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

Ниже приведен пример отправки данных в формате JSON:

Здесь используется импровизированная структура данных, состоящая из начальной и конечной даты, а также массива номеров некоторых условных записей. Обратите внимание на то, что в заголовке запроса Content-Type указывается тип “application/json”.

Получение данных

Для того чтобы получить переданные данные вышеописанным способом требуется произвести чтение данных из потока ввода “php://input”.

Используемые функции для принятия данных:

Ниже приведен пример получения данных в формате JSON на стороне сервера:

Полученная структура данных:

Примечание: необходимо учитывать тот момент, что для работы с форматом JSON, данные должны быть в кодировке utf-8.

Предоставленные JSON константы для функции json_encode()

JSON_HEX_TAG (integer)Все кодируются в \u003C и \u003E. Доступна начиная с PHP 5.3.0.
JSON_HEX_AMP (integer)Все & кодируются в \u0026. Доступна начиная с PHP 5.3.0.
JSON_HEX_APOS (integer)Все символы ‘ кодируются в \u0027. Доступна начиная с PHP 5.3.0.
JSON_HEX_QUOT (integer)Все символы » кодируются в \u0022. Доступна начиная с PHP 5.3.0.
JSON_FORCE_OBJECT (integer)Выдавать объект вместо массива при использовании неассоциативного массива. Это полезно, когда принимающая программа или код ожидают объект или же массив пуст. Доступна начиная с PHP 5.3.0.
JSON_NUMERIC_CHECK (integer)Кодирование строк, содержащих числа, как числа. Доступна начиная с PHP 5.3.3.
JSON_BIGINT_AS_STRING (integer)Кодирует большие целые числа в виде их строковых эквивалентов. Доступна начиная с PHP 5.4.0.
JSON_PRETTY_PRINT (integer)Использовать пробельные символы в возвращаемых данных для их форматирования. Доступна начиная с PHP 5.4.0.
JSON_UNESCAPED_SLASHES (integer)Не экранировать /. Доступна начиная с PHP 5.4.0.
JSON_UNESCAPED_UNICODE (integer)Не кодировать многобайтные символы Unicode (по умолчанию они кодируются как \uXXXX). Доступна начиная с PHP 5.4.0.

Список возможных режимов для fopen() используя mode

‘r’Открывает файл только для чтения; помещает указатель в начало файла.
‘r+’Открывает файл для чтения и записи; помещает указатель в начало файла.
‘w’Открывает файл только для записи; помещает указатель в начало файла и обрезает файл до нулевой длины. Если файл не существует — пробует его создать.
‘w+’Открывает файл для чтения и записи; помещает указатель в начало файла и обрезает файл до нулевой длины. Если файл не существует — пытается его создать.
‘a’Открывает файл только для записи; помещает указатель в конец файла. Если файл не существует — пытается его создать.
‘a+’Открывает файл для чтения и записи; помещает указатель в конец файла. Если файл не существует — пытается его создать.
‘x’Создаёт и открывает только для записи; помещает указатель в начало файла. Если файл уже существует, вызов fopen() закончится неудачей, вернёт FALSE и выдаст ошибку уровня E_WARNING. Если файл не существует, попытается его создать. Это эквивалентно указанию флагов O_EXCL|O_CREAT для внутреннего системного вызова open(2).
‘x+’Создаёт и открывает для чтения и записи; иначе имеет то же поведение что и’x’.
‘c’Открывает файл только для записи. Если файл не существует, то он создается. Если же файл существует, то он не обрезается (в отличии от ‘w’), и вызов к этой функции не вызывает ошибку (также как и в случае с ‘x’). Указатель на файл будет установлен на начало файла. Это может быть полезно при желании заблокировать файл (смотри flock()) перед изменением, так как использование ‘w’ может обрезать файл еще до того как была получена блокировка (если вы желаете обрезать файл, можно использовать функцию ftruncate() после запроса на блокировку).
‘c+’Открывает файл для чтения и записи; иначе имеет то же поведение, что и ‘c’.

Комментариев: 5

php получение post запроса json. Смотреть фото php получение post запроса json. Смотреть картинку php получение post запроса json. Картинка про php получение post запроса json. Фото php получение post запроса jsonlavrik
30.04.2014 @ 10:37 дп

Источник

Принципы построения REST JSON API

php получение post запроса json. Смотреть фото php получение post запроса json. Смотреть картинку php получение post запроса json. Картинка про php получение post запроса json. Фото php получение post запроса jsonЭта памятка писалась для внутренних нужд (открыть глаза менее опытным в вебе коллегам). Но, т.к. я насмотрелся велосипедов от довольно уважаемых, казалось бы, контор, — выкладываю на хабр. Мне кажется, многим будет полезно.

Зачем

Надеюсь, читающий уже понимает, зачем ему вообще нужен именно REST api, а не какой-нибудь монстр типа SOAP. Вопрос в том, зачем соблюдать какие-то стандарты и практики, если браузеры вроде бы позволяют делать что хочешь.

Структура запросов и ответов

Любой http-запрос начинается со строки

где METHOD — это метод доступа (GET, PUT и т.д.), а URI — адрес запрашиваемого ресурса.

В начале запроса идут заголовки — просто текстовые строки вида key: value
Затем передаётся пустая строка, означающая конец секции заголовков, и затем — тело запроса, если оно есть.

В ответе сначала передаётся строка с версией http, кодом и строковым статусом ответа (например HTTP/1.1 200 OK ), далее текстовые заголовки ответа, потом пустая строка, потом тело ответа.

Тут вроде всё просто.

Кодирование запросов и ответов

Кодировка для всех и запросов, и ответов — UTF-8 и только UTF-8, т.к. некоторые, кхм, «браузеры» имеют привычку игнорировать содержимое заголовка charset.

Использование кодов символов и html-сущностей не допускается, т.е. режим JSON_UNESCAPED_UNICODE обязателен. Не все клиенты знают всю таблицу html сущностей (типа каких-нибудь ù ), да и при чём тут html. Не все клиенты готовы/хотят заниматься перекодированием \uXXXX; и &#XX;. Плюс возможны «весёлые» ситуации с избыточным экранированием или пропаданием слэшей и амперсандов.

Все данные, кроме URI и двоичных файлов, передаются в формате JSON. Обратите внимание, что далеко не всякий валидный javascript код является валидным JSON.
В частности, для строк используются только двойные кавычки. Одинарные кавычки в json-данных, хотя и допустимы в «обычном» javascript, могут вызвать непредсказуемые плохо отлавливаемые баги.

В запросах обязательно указывается заголовок

Вызовы к API отличаются от прочих вызовов (например, обычной загрузки html страницы по данному URI) именно по наличию application/json в Accept.

В ответах 2хх с непустым телом обязательно наличие заголовка ответа

При наличии тела запроса также обязателен заголовок запроса

либо, при загрузке файлов,

и далее, в первой части

после чего для каждого файла

Если вы используете защиту от CSRF (а лучше бы вам её использовать), то удобнее передавать CSRF-токен в отдельном заголовке (типа X-CSRF-Token) для всех запросов, а не внедрять вручную в каждый запрос. Хранить CSRF токен в куках плохо по той причине, что куки можно украсть, в чём собственно и состоит суть CSRF атаки.

Структура URI

Нагородить можно всякое, но лучшая практика — чтобы все URI имели вид

ну, или если у вас api лежит в какой-то папке,

Для разбора части URI до знака вопроса можно использовать регулярку

Ведущий слэш обязателен, т.к. неизвестно, с какого URL будет осуществлён запрос.

Методы HTTP

GET /:entity/:id — getById

В случае успеха сервер возвращает 200 OK с полями объекта в формате JSON в теле ответа (без дополнительного оборачивания в какой-либо объект)

В случае, если объект с такими id не существует, сервер возвращает 404 Not Found

В ответе обязательно должны быть заголовки, касающиеся политики кэширования, т.к. браузеры активно кешируют GET и HEAD запросы. При остутствии какой-либо политики управления кэшем должно быть:

GET /:entity[?param1=. &param2=. ] — списочный get

Простой случай: в случае успеха сервер возвращает 200 OK с массивом объектов в формате JSON в теле ответа (т.е. ответ начинается с [ и заканчивается ] ).

Если массив получился пустой, всё равно вовзращается 200 OK с пустым масивом [] в теле ответа.

Более сложный вариант: возвращается объект, в одном из полей которого — искомый массив. В остальных полях — данные о пагинации, фильтры, счётчики и пр. Только держите это консистентным по всем api.

HEAD /:entity[/:id] — запрос заголовков

Полный аналог GET с таким же URI, но не возвращает тело ответа, а только HTTP-заголовки.

Реализация поддержки HEAD запросов веб-сервером обязательна.

Активно используется браузерами в качестве автоматических pre-flight запросов перед выполнением потенциально опасных, по их мнению, операций. Например, браузер Chrome активно кидается head-запросами для получения политик CORS при кросс-доменных операциях (виджеты и пр). При этом ошибка обработки такого head-запроса приведёт к тому, что основной запрос вообще не будет выполнен браузером.

Может использоваться для проверки существования объекта без его передачи (например, для больших объектов типа мультимедиа-файлов).

POST /:entity — создаёт новый объект типа :entity

В теле запроса должны быть перечислены поля объекта в формате JSON без дополнительного заворачивания, т.е.

В случае успеха сервер должен возвращать 201 Created с пустым телом, но с дополнительным заголовком

указывающим на месторасположение созданного объекта.

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

Также метод POST используется для удалённого вызова процедур (RPC), в этом случае ответ будет иметь статус 200 OK и результаты в теле. Вообще смешивать REST и RPC в одном api — идея сомнительная, но всякое бывает.

Единственный неидемпотентный некешируемый метод, т.е. повтор двух одинаковых POST запросов создаст два одинаковых объекта.

PUT /:entity/:id — изменяет объект целиком

В запросе должны содержаться все поля изменяемого объекта в формате JSON.

В случае успеха должен возвращать 204 No Data с пустым телом, т.к. у клиента есть все необходимые данные.

Идемпотентный запрос, т.е. повторный PUT с таким же телом не приводит к каким-либо изменениям в БД.

PATCH /:entity/:id — изменяет отдельные поля объекта

В запросе должны быть перечислены только поля, подлежащие изменению.

В случае успеха возвращает 200 OK с телом, аналогичным запросу getById, со всеми полями изменённого объекта.

Используется с осторожностью, т.к. два параллельных PATCH от двух разных клиентов могут привести объект в невалидное состояние.

DELETE /:entity/:id — удаляет объект, если он существует.

В случае успеха возвращает 204 No Data с пустым телом, т.к. возвращать уже нечего.

Идемпотентный запрос, т.е. повторный DELETE с таким же адресом не приводит к ошибке 404.

OPTIONS /:entity[/:id]

Получает список методов, доступных по данному URI.

Сервер должен ответить 200 OK с дополнительным заголовком

Некешиуремый необязательный метод.

Обработка ошибок

Возвращаемые ошибки передаются с сервера на клиент как ответы со статусами 4хх (ошибка клиента) или 5хх (ошибка сервера). При этом описание ошибки, если оно есть, приводится в теле ответа в формате text/plain (без всякого JSON). Соответственно, передаётся заголовок ответа

Использовать html для оформления сообщений об ошибках в api — так себе идея, будут проблемы журналированием и т.д. Предполагается, что клиент способен сам красиво оформить сообщение об ошибке для пользователя.

При выборе конкретных кодов ошибок не следует слишком увлекаться и пытаться применить существующие коды только потому, что название кажется подходящим. У многих кодов есть дополнительные требования к наличию определённых заголовков и специальная обработка браузерами. Например, код 401 запускает HTTP-аутентификацию, которая будет странно смотреться в каком-нибудь приложении на react или electron.

UPD по мотивам комментариев. Клиенты у вас будут разные: не только веб и мобильные приложения, но и такие штуки, как запускалка интеграционных тестов (CI), балансировщик нагрузки или система мониторинга у админов. Использование или неиспользование того или иного статуса ошибки определяется тем, будет ли он полезен хоть какому-то клиенту (т.е. этот клиент сможет предпринять какие-то действия конкретно по этому коду) и, наоборот, не будет ли проблем у какого-то из клиентов из-за неиспользования вами этого кода. Придумать реальный use-case, когда реакция клиента будет различаться в зависимости от 404 или 410, довольно сложно. При этом отличий 404 от 200 или 500 — вагон и телега.

400 Bad Request

Универсальный код ошибки, если серверу непонятен запрос от клиента.

403 Forbidden

Возвращается, если операция запрещена для текущего пользователя. Если у оператора есть учётка с более высокими правами, он должен перелогиниться самостоятельно. См. также 419

404 Not Found

Возвращается, если в запросе был указан неизвестный entity или id несуществующего объекта.

Списочные методы get не должны возвращать этот код при верном entity (см. выше).

Если запрос вообще не удалось разобрать, следует возвращать 418.

415 Unsupported Media Type

Возвращается при загрузке файлов на сервер, если фактический формат переданного файла не поддерживается. Также может возвращаться, если не удалось распарсить JSON запроса, или сам запрос пришёл не в формате JSON.

418 I’m a Teapot

Возвращается для неизвестных серверу запросов, которые не удалось даже разобрать. Обычно это указывает на ошибку в клиенте, типа ошибки при формировании URI, либо что версии протокола клиента и сервера не совпадают.

419 Authentication Timeout

Отправляется, если клиенту нужно пройти повторную авторизацию (например, протухли куки или CSRF токены). При этом на клиенте могут быть несохранённые данные, которые будут потеряны, если просто выкинуть клиента на страницу авторизации.

422 Unprocessable Entity

Запрос корректно разобран, но содержание запроса не прошло серверную валидацию.

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

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

500 Internal Server Error

Возвращается, если на сервере вылетело необработанное исключение или произошла другая необработанная ошибка времени исполнения.

Всё, что может сделать клиент в этом случае — это уведомить пользователя и сделать console.error(err) для более продвинутых товарищей (админов, разработчиков и тестировщиков).

501 Not Implemented

Возвращается, если текущий метод неприменим (не реализован) к объекту запроса.

Ну вот, в общем-то, и всё. Спасибо за внимание!

Источник

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

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