что такое json api

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

В итоге GET не имеет тела и использует URI для указания сущности (т. Е. / Books) и, при необходимости, дополнительных параметров запроса (т. Е. Id / 24). POST, PUT и DELETE не должны указывать параметры запроса через URI, а использовать тело сообщения для передачи информации о том, что должно быть создано, изменено или удалено.

Ответы с сервера

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

HTTP-ответ уже содержит состояние (дополнительную информацию о кодах состояния можно найти в определениях кодов состояния ). Мы можем улучшить это с помощью метаинформации, которая может содержать дополнительную информацию. Дополнительная информация, специфичная для реализации на сервере, может быть предоставлена, например, с ошибкой и сообщением. Как правило, когда клиент получает ответ со статусом HTTP 2XX, запрос был успешным. Ответы со статусом 4XX представляют ошибки, спровоцированные клиентом (т.е. отсутствуют обязательные данные), а 5XX — ошибки сервера.

Данные должны быть указаны, даже если они не отправлены с сервера.

Источник

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

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

Зачем

Надеюсь, читающий уже понимает, зачем ему вообще нужен именно 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

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

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

Источник

API. Что это такое, зачем существует, в чем преимущества. JSON

Для начала стоит обратиться к википедии за определением того, что такое API.

API (интерфейс программирования приложений, интерфейс прикладного программирования) (англ. application programming interface, API) — набор готовых классов, процедур, функций, структур и констант, предоставляемых приложением (библиотекой, сервисом) или операционной системой для использования во внешних программных продуктах.

Итак определение дано. Набор готовых классов, процедур, функций, структур и констант, которые предоставляютися приложением/библиотекой/сервисом для использования во внешних программных продуктах. Вот они те самые ключевые слова, которые объясняют — с какой целью создавалось такое понятие, как API.

Примеры API

Пример, когда вам необходимо пользоваться API

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

Какие есть варианты решения этой задачи?

Найти сайт банка, у которого отображается данная информация и парсить

В целом это работает. Вы запросите страницу, получите HTML-код, с помощью специальных библиотек, либо с помощью саморучно написанного парсера — вы получите данную информацию.

Вы становитесь заложником структуры и функциональности сайта банка:

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

Найти/запросить API для получения этих данных

Это правильный подход. В ходе запроса в поисковике «курс валют API JSON» я в течении 2 минут нашел соответствующий endpoint:

У этого сервиса есть также данные в формате XML, но так как на данном сайте есть уже информация о том, как работать с JSON — я выбрал JSON.

Это всего лишь разные форматы предоставления данных в сериализованном виде.

Итак у нас есть источник. Так называемый API endpoint. Так как C# строготипизированный язык — нам нужно знать структуру получаемых данных. Открываем ссылку выше на endpoint и копируем содержимое. На данный момент оно выглядит следующим образом:

Часть данных я стер, так как нам это интересно для примера. Я оставил только доллар и евро.

Заходим на сайт: json2csharp и вставляем эти данные в поле для ввода. После нажатия на кнопку «Generate» вы увидите классы, которые вам необходимы для работы.

Главный объект — это RootObject. Его можно переименовать в тот, который вам больше подходит. Я оставлю как есть.

У объекта Valute есть:

Объекты USD и EUR уже содержат в себе данные курса валют. То есть для того, чтобы получить курс доллара — нам нужно обратиться к RootObject.Valute.USD.Value. Уже неплохо.

где jsonString- это строка с данными из URL API-endpoint.

В чем преимущества?

Серьезные преимущества, не так ли?

А главное — скорость.

Пример, когда вам необходимо написать сервис с API

Вы пишите платный сервис, который делает email рассылку.

Если ваш сервис успешно выполнил операцию, то отвечает

То есть операция прошла успешно.

Если неверные учетные данные, то ответ будет таким:

Если не хватило денег на балансе клиента на отправку сообщения (сервис то платный), то ответ будет таким:

Теперь пользователи вашего сервиса смогут запрограммировать свой сайт/сервис/настольное приложения для использования вашего сервиса для рассылки почты.

Где ещё применяется API?

Именно удобство пользования и универсальность делают очень популярными в сегодняшние дни API.

О последним расскажу вкратце.

AJAX-Frontend

Наверное многие хотя бы раз слышали о таких вещах как:

Это далеко не все представители динамичного формирования конечного HTML-кода страницы на стороне браузера.

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

Например сайт VK. Когда вы прокручиваете свою ленту — она грузится динамично. Как долистали до самого низа — в неё подгрузилось определенное количество объектов. Без этой технологии вы бы видели внизу страницы так называемый paginator, блок, в котором бы вы видели общее количество страниц вашей ленты и могли бы листать её таким образом.

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

В чем же преимущества сайта, который разделен на независимые логические части как Frontend-сайт и Backend-API?

Если остались вопросы — задавайте в комментариях 🙂

Источник

Что такое JSON

Если вы тестируете API, то должны знать про два основных формата передачи данных:

XML — используется в SOAP (всегда) и REST-запросах (реже);

JSON — используется в REST-запросах.

Сегодня я расскажу вам про JSON. И расскажу в основном с точки зрения «послать запрос в Postman или прочитать ответ», потому что статья рассчитана на студентов, впервые работающих с Postman.

JSON (англ. JavaScript Object Notation) — текстовый формат обмена данными, основанный на JavaScript. Но при этом формат независим от JS и может использоваться в любом языке программирования.

JSON используется в REST API. По крайней мере, тестировщик скорее всего столкнется с ним именно там.

Что такое API — общее знакомство с API

Что такое XML — второй популярный формат

В SOAP API возможен только формат XML, а вот REST API поддерживает как XML, так и JSON. Разработчики предпочитают JSON — он легче читается человеком и меньше весит. Так что давайте разберемся, как он выглядит, как его читать, и как ломать!

Содержание

Как устроен JSON

В качестве значений в JSON могут быть использованы:

Число (целое или вещественное)

Литералы true (логическое значение «истина»), false (логическое значение «ложь») и null

Я думаю, с простыми значениями вопросов не возникнет, поэтому разберем массивы и объекты. Ведь если говорить про REST API, то обычно вы будете отправлять / получать именно json-объекты.

JSON-объект

Как устроен

И разберемся, что означает эта запись.

Объект заключен в фигурные скобки <>

JSON-объект — это неупорядоченное множество пар «ключ:значение».

Ключ — это название параметра, который мы передаем серверу. Он служит маркером для принимающей запрос системы: «смотри, здесь у меня значение такого-то параметра!». А иначе как система поймет, где что? Ей нужна подсказка!

Вот, например, «Виктор Иван» — это что? Ищем описание параметра «query» в документации — ага, да это же запрос для подсказок!

Это как если бы мы вбили строку «Виктор Иван» в GUI (графическом интерфейсе пользователя):

Когда пользователь начинает вводить данные в формочку, то сразу видит результат — появляется список подсказок. Это значит, что разработчик прописал в коде условие — делать некое действие на каждый ввод символа в это поле. Какое действие? Можно увидеть через f12.

Открываем вкладку Network, вбиваем «Виктор Иван» и находим запрос, который при этом уходит на сервер. Ого, да это тот самый пример, что мы разбираем!

Клиент передает серверу запрос в JSON-формате. Внутри два параметра, две пары «ключ-значение»:

query — строка, по которой ищем (то, что пользователь вбил в GUI);

count — количество подсказок в ответе (в Дадате этот параметр зашит в форму, всегда возвращается 7 подсказок. Но если дергать подсказки напрямую, значение можно менять!)

Пары «ключ-значение» разделены запятыми:

Строки берем в кавычки, числа нет:

Конечно, внутри может быть не только строка или число. Это может быть и другой объект! Или массив. Или объект в массиве, массив в объекте. Любое количество уровней вложенности =))

Объект, массив, число, булево значение (true / false) — если у нас НЕ строка, кавычки не нужны. Но в любом случае это будет значение какого-то ключа:

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

Так правильно

Так тоже правильно

Ключ — ВСЕГДА строка, но мы все равно берем его в кавычки. В JavaScript этого можно не делать, в JSON нельзя.

Так правильно

Так правильно в JS, но неправильно в JSON

По крайней мере, если вы работаете с простыми значениями ключей, а несколько слов записываете в верблюжьемРегистре или в змеином_регистре. Если вы хотите написать в ключе несколько слов через пробел, ключ нужно взять в кавычки.

my query: «Виктор Иван»

«my query»: «Виктор Иван»

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

Писать ключи можно в любом порядке. Ведь JSON-объект — это неупорядоченное множество пар «ключ:значение».

Так правильно

Так тоже правильно

Очень важно это понимать, и тестировать! Принимающая запрос система должна ориентировать на название ключей в запросе, а не на порядок их следования. Ключевое слово «должна» )) Хотя знаю примеры, когда от перестановки ключей местами всё ломалось, ведь «первым должен идти запрос, а не count!».

Ключ или свойство?

Вот у нас есть JSON-объект:

Что такое «query»? Если я хочу к нему обратиться, как мне это сказать? Есть 2 варианта, и оба правильные:

— Обратиться к свойству объекта;

— Получить значение по ключу.

То есть «query» можно назвать как ключом, так и свойством. А как правильно то?

Правильно и так, и так! Просто есть разные определения объекта:

Объект

В JS объект — это именно объект. У которого есть набор свойств и методов:

Свойства — описывают, ЧТО мы создаем.

Методы — что объект умеет ДЕЛАТЬ.

То есть если мы хотим создать машину, есть два пути:

Перечислить 10 разных переменных — модель, номер, цвет, пробег.

Создать один объект, где будут все эти свойства.

Аналогично с кошечкой, собачкой, другом из записной книжки.

Объектно-ориентированное программирование (ООП) предлагает мыслить не набором переменных, а объектом. Хотя бы потому, что это логичнее. Переменных в коде будет много, как понять, какие из них взаимосвязаны?

Вот если я создаю машину, сколько переменных мне надо заполнить? А если меняю данные? А если удаляю? Когда переменные разбросаны по коду, можно забыть про какую-то и получить ошибку в интерфейсе. А если у нас есть цельный объект, всегда можно посмотреть, какие у него есть свойства и методы.

Например, создадим кошечку:

В объекте cat есть:

Свойства — name, year (что это за кошечка)

Функции — sleep (что она умеет делать, описание поведения)

По коду сразу видно, что у кошечки есть имя и возраст, она умеет спать. Если разработчик решит добавить новые свойства или методы, он дополнит этот объект, и снова всё в одном месте.

Если потом нужно будет получить информацию по кошечке, разработчик сделает REST-метод getByID, searchKitty, или какой-то другой. А в нем будет возвращать свойства объекта.

То есть метод вернет

И при использовании имени вполне уместно говорить «обратиться к свойству объекта». Это ведь объект (кошечка), и его свойства!

Набор пар «ключ:значение»

Второе определение объекта — неупорядоченное множество пар ключ:значение, заключенное в фигурные скобки <>.

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

client_fio (в коде это свойство fio объекта client)

kitty_name (в коде это свойство name объекта cat)

car_model (в коде это свойство model объекта car)

В таком случае логично называть эти параметры именно ключами — мы хотим получить значение по ключу.

Но в любом случае, и «ключ», и «свойство» будет правильно. Не пугайтесь, если в одной книге / статье / видео увидели одно, в другой другое. Это просто разные трактовки ¯\_(ツ)_/¯

Итого

Json-объект — это неупорядоченное множество пар «ключ:значение», заключённое в фигурные скобки «< >». Ключ описывается строкой, между ним и значением стоит символ «:». Пары ключ-значение отделяются друг от друга запятыми.

Значения ключа могут быть любыми:

И только строку мы берем в кавычки!

JSON-массив

Как устроен

Давайте снова начнем с примера. Это массив:

Массив заключен в квадратные скобки []

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

Значения разделены запятыми:

Значения внутри

Внутри массива может быть все, что угодно:

Цифры

Строки

Смесь

Объекты

Да, а почему бы и нет:

Или даже что-то более сложное. Вот пример ответа подсказок из Дадаты:

Система возвращает массив подсказок. Сколько запросили в параметре count, столько и получили. Каждая подсказка — объект, внутри которого еще один объект. И это далеко не сама сложная структура! Уровней вложенности может быть сколько угодно — массив в массиве, который внутри объекта, который внутри массива, который внутри объекта.

Ну и, конечно, можно и наоборот, передать массив в объекте. Вот пример запроса в подсказки:

Это объект (так как в фигурных скобках и внутри набор пар «ключ:значение»). А значение ключа «parts» — это массив элементов!

Итого

Массив — это просто набор значений, разделенных запятыми. Находится внутри квадратных скобок [].

А вот внутри него может быть все, что угодно:

смесь из всего вышеназванного

JSON vs XML

В SOAP можно применять только XML, там без вариантов.

В REST можно применять как XML, так и JSON. Разработчики отдают предпочтение json-формату, потому что он проще воспринимается и меньше весит. В XML есть лишняя обвязка, название полей повторяется дважды (открывающий и закрывающий тег).

Сравните один и тот же запрос на обновление данных в карточке пользователя:

JSON

За счет того, что мы не дублируем название поля каждый раз «surname – surname», читать JSON проще. И за счет этого же запрос меньше весит, что при плохом интернете бывает важно. Или при большой нагрузке.

Well Formed JSON

Разработчик сам решает, какой JSON будет считаться правильным, а какой нет. Но есть общие правила, которые нельзя нарушать. Наш JSON должен быть well formed, то есть синтаксически корректный.

Чтобы проверить JSON на синтаксис, можно использовать любой JSON Validator (так и гуглите). Я рекомендую сайт w3schools. Там есть сам валидатор + описание типичных ошибок с примерами.

Но учтите, что парсеры внутри кода работают не по википедии или w3schools, а по RFC, стандарту. Так что если хотите изучить «каким должен быть JSON», то правильнее открывать RFC и искать там JSON Grammar. Однако простому тестировщику хватит набора типовых правил с w3schools, их и разберем.

Правила well formed JSON:

Данные написаны в виде пар «ключ:значение»

Данные разделены запятыми

Объект находится внутри фигурных скобок <>

Массив — внутри квадратных []

1. Данные написаны в виде пар «ключ:значение»

В JSON название ключа нужно брать в кавычки, в JavaScript не обязательно — он и так знает, что это строка. Если мы тестируем API, то там будет именно JSON, так что кавычки обычно нужны.

Но учтите, что это правило касается JSON-объекта. Потому что json может быть и числом, и строкой. То есть:

Это тоже корректный json, хоть и не в виде пар «ключ:значение».

И вот если у вас по ТЗ именно json-объект на входе, попробуйте его сломать, не передав ключ. Ещё можно не передать значение, но это не совсем негативный тест — система может воспринимать это нормально, как пустой ввод.

2. Данные разделены запятыми

Пары «ключ:значение» в объекте разделяются запятыми. После последней пары запятая не нужна!

Типичная ошибка: поставили запятую в конце объекта:

Это последствия копипасты. Взяли пример из документации, подставили в постман (ну или разработчик API подставил в код, который будет вызывать систему), а потом решили поменять поля местами.

Смотрим на запрос — ну, query то важнее чем count, надо поменять их местами! Копипастим всю строку ««count»: 7,», вставляем ниже. Перед ней запятую добавляем, а «лишнюю» убрать забываем. По крайней мере у меня это частая ошибка, когда я «кручу-верчу, местами поменять хочу».

Другой пример — когда мы добавляем в запрос новое поле. Примерный сценарий:

У меня уже есть работающий запрос в Postman-е. Но в нем минимум полей.

Копирую из документации нужное мне поле. Оно в примере не последнее, так что идёт с запятой на конце.

Вставляю себе в конце запроса — в текущий конец добавляю запятую, потом вставляю новую строку.

Отправляю запрос — ой, ошибка! Из копипасты то запятую не убрала!

Я на этот сценарий постоянно напарываюсь при тестировании перестановки полей. А ведь это нужно проверять! Хороший запрос должен быть как в математической присказке: «от перемены мест слагаемых сумма не меняется».

Не зря же определение json-объекта гласит, что «это неупорядоченное множество пар ключ:значение». Раз неупорядоченное — я могу передавать ключи в любом порядке. И сервер должен искать по запросу название ключа, а не обращаться к индексу элемента.

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

Чтобы протестировать, как система обрабатывает «плохой json», замените запятую на точку с запятой:

Или добавьте лишнюю запятую в конце запроса — эта ошибка будет встречаться чаще!

Или пропустите запятую там, где она нужна:

Аналогично с массивом. Данные внутри разделяются через запятую. Хотите попробовать сломать? Замените запятую на точку с запятой! Тогда система будет считать, что у вас не 5 значений, а 1 большое:

*Я добавила комментарии внутри блока кода. Но учтите, что в JSON комментариев нет. Вообще. Так что если вы делаете запрос в Postman, не получится расставить комментарии у разных строчек в JSON-формате.

3. Объект находится внутри фигурных скобок <>

Чтобы сломать это условие, уберите одну фигурную скобку:

Или попробуйте передать объект как массив:

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

4. Массив — внутри квадратных []

Чтобы сломать это условие, уберите одну квадратную скобку:

Или попробуйте передать массив как объект, в фигурных скобках:

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

Итого

JSON (JavaScript Object Notation) — текстовый формат обмена данными, основанный на JavaScript. Легко читается человеком и машиной. Часто используется в REST API (чаще, чем XML).

Корректные значения JSON:

JSON-объект — неупорядоченное множество пар «ключ:значение», заключённое в фигурные скобки «< >».

Массив — упорядоченный набор значений, разделенных запятыми. Находится внутри квадратных скобок [].

Число (целое или вещественное).

Литералы true (логическое значение «истина»), false (логическое значение «ложь») и null.

При тестировании REST API чаще всего мы будем работать именно с объектами, что в запросе, что в ответе. Массивы тоже будут, но обычно внутри объектов.

Комментариев в JSON, увы, нет.

Правила well formed JSON:

Данные в объекте написаны в виде пар «ключ:значение»

Данные в объекте или массиве разделены запятыми

Источник