Программные интерфейсы

спринт Программные интерфейсы
Компьютерная сеть и протоколы
6/6
О чём этот спринт
Сетевая модель OSI
Сетевая модель TCP/IP
HTTP-запрос
Параметры HTTP-запроса
HTTP-ответ
Стили представления данных
2/2
JSON
XML
Postman
2/2
Стили взаимодействия
4/4
Проектирование взаимодействия
1/1
Воркшоп и домашнее задание
1/2
Заключение
1/1

JSON

В предыдущих уроках для описания тела и параметров HTTP-запроса использовался стиль представления данных JSON. В этом уроке вы научитесь читать данные, которые представлены в этом стиле, узнаете особенности его пунктуации и познакомитесь с разными JSON-схемами.
Айгуль
“напиток”: “кофе” и “перекус”: “яблоко”?
Даня
Чего? 😓
Айгуль
Или “напиток”: “чай”?
Даня
Что-то знакомое…
Айгуль
Это я проверяю, помнишь ли ты наборы ключ:значение. Они нам сейчас понадобятся!
Даня
Зачем?
Айгуль
Будем учиться читать данные в стиле представления JSON!

Стили представления данных

Вы уже знаете, что приложения редко существуют изолированно от других приложений. Между ними идёт постоянный обмен данными. Но приложения обмениваются не абстрактным набором информации. Данные следует представлять в таком виде, в котором стороннее приложение сможет их обработать. Поэтому, когда запрашиваемый ресурс возвращает данные, они проходят сериализацию.
Сериализация — это преобразование набора данных в определённый формат. Сериализация похожа на заполнение анкеты на сайте: пользователю нужно представить данные о себе по определённым правилам. На разных сайтах вас могут попросить представить одни и те же данные о себе в разном виде, при этом сами данные и их источник будут одинаковыми.
Набор синтаксических правил оформления данных, которыми обмениваются приложения, называется стилем представления данных (Data Representation Style). Наиболее распространёнными стилями являются:
  • JSON,
  • XML.
Использование разных стилей представления данных даёт возможность изолированно разрабатывать элементы архитектуры ПО, то есть независимо друг от друга, а так же управлять процессом взаимодействия между приложениями.

JSON

Самый популярный стиль представления данных — это нотация объектов JavaScript (JavaScript Object Notation — JSON). Свою популярность он заслужил своей простотой, легкостью чтения и несложным набором правил.
В JSON объект — это такой элемент структуры, который содержит в себе набор данных. В соответствии с JSON начало и конец каждого объекта обозначается фигурными скобками.
JSON
{

}
Каждый объект состоит из множества уже знакомых вам наборов ключ:значение (Key:Value). Один объект от другого можно отличить по их свойствам. Например, бокал отличается от тарелки объёмом, материалом, формой. Эти свойства объекта называются ключами. Каждый ключ содержит одно или несколько значений (Value). Например, свойства бокала можно описать так:
Ключ (key)Значение (value)
Форма (shape)«Тюльпан»
Объём в миллилитрах (volume)300
Материал (material)хрусталь, позолота
Хрупкость (fragile)да

Ключ

В соответствии с JSON ключ должен быть описан по следующим правилам:
  1. Название ключа записывается латиницей и помещается в кавычки.
  2. После ключа ставится двоеточие и указывается значение.
  3. Ключи внутри объекта отделяются друг от друга запятыми.
Таким образом, ключи, которые указаны в таблице, можно представить так:
JSON
{
"shape": "значение ключа",
"volume": "значение ключа",
"material": "значение ключа",
"fragile": "значение ключа"
}

Значение

У каждого ключа есть значение. В JSON значения отличаются по типу данных:
  • cтрока (string) — значение может быть описано любым набором символов (кириллица, латиница, цифры, символы, в том числе пробел, и прочие). Значение, которое указано таким способом, будет отображаться пользователю без изменений. Такой тип данных всегда берётся в кавычки.
Важно отметить, что только значения с типом данных строка берутся в кавычки.
  • Число (number) — значение описывается цифрами. Допустимо использовать символы для обозначения отрицательных (-1) и дробных чисел (1.1).
  • Логическое значение (boolean) может быть описано как:
    • истина (true) или ложь (false).
      Например, у объектов есть свойство «хрупкость». Если объект описывает бокал, хрупкий предмет, то свойство «хрупкость» примет значение «истина» (true). А если объект описывает скатерть, нехрупкий предмет, то свойство «хрупкость» примет значение «ложь» (false).
  • Null соответствует понятию «пустое». Иными словами, ключ не содержит никакого значения.
  • Массив (array) описывает множество значений одного и того же ключа. Начало и конец массива обозначаются квадратными скобками. Внутри массив содержит множество элементов одного типа, которые отделяются друг от друга запятыми.
Ключи и их значения из таблицы со свойствами бокала можно представить в виде одного объекта с набором свойств и их значений. Значение ключа "shape" имеет тип «строка», значение ключа "volume" имеет тип «число», значение ключа "material" имеет тип «массив», значение ключа "fragile" имеет логический тип. Предположим, что у объектов в системе есть необязательное свойство «температура глажки» (ironingTemperature). Например, для скатерти значение этого ключа может быть указано, но у бокала этого значения нет, поэтому в объекте будет присутствовать ключ со значением null:
JSON
{
    "shape": "Тюльпан",
    "volume": 300,
    "material": ["хрусталь", "позолота"],
    "fragile":  true,
    "ironingTemperature": null
}
Значение ключа также можно представить, как объект, состоящий из объектов.
Например, производитель (vendor) — одно из свойств бокала, у которого также можно выделить несколько свойств: название (name) и страна (country). В JSON подобная вложенность заключается в отдельные фигурные скобки (как для обозначения начала и конца объекта), а свойства внутри неё так же берут в кавычки и отделяют запятыми:
JSON
{
 "key_1": "value_1",
 "key_2": {
   "key_3": "property_1",
   "key_4": "property_2",
  }
}
Для нашего примера JSON может выглядеть так:
JSON
{
    "shape": "Тюльпан",
    "volume": 300,
    "material": ["хрусталь", "позолота"],
    "fragile":  true,
    "ironingTemperature": null
    "vendor": {
         "name": "Королевская хрустальная мануфактура",
         "country": "Великобритания"
  }
}
Перед вами пример тела ответа, который написан в соответствии с JSON. В нём пропущены элементы пунктуации. Выберите из списка символы, которые должны быть на месте пропусков.
JSON
ПРОПУСК1
   "vendor": {
      "name": "Королевская хрустальная мануфактура",
      "country": "ВеликобританияПРОПУСК2
      "city": "Суиндон"
   ПРОПУСК3
}
Символ на месте ПРОПУСК1:
{
Символ на месте ПРОПУСК2:
",
Символ на месте ПРОПУСК3:
}
Так будет выглядеть правильный вариант оформления:
JSON
{
   "vendor": {
      "name": "Королевская хрустальная мануфактура",
      "country": "Великобритания",
      "city": "Суиндон"
   }
}
Теперь попробуйте решить задачу посложнее. Заполните пропуски нужными символами и ключами.
JSON
{
   ПРОПУСК1: {
      "name": "Королевская хрустальная мануфактура",
      "country": "Великобритания",
      "city": ПРОПУСК2
      "street": "Келлсборо-авеню",
      "house": ПРОПУСК3
      "email": "royal-crystal@buckingham.com"
   }
}
Что должно быть на месте Пропуска 1?
"vendor"
Что должно быть на месте Пропуска 2?
“Лондон”,
Что должно быть на месте Пропуска 3?
12,
Так будет выглядеть правильный вариант оформления:
JSON
{
   "vendor": {
      "name": "Королевская хрустальная мануфактура",
      "country": "Великобритания",
      "city": "Лондон",
      "street": "Келлсборо-авеню",
      "house": 12,
      "email": "royal-crystal@buckingham.com"
   }
}

JSON-схема

Чтобы приложения могли обмениваться данными в формате JSON, на этапе разработки нужно чётко определить структуру используемых объектов и иметь инструкцию с подробным описанием каждого свойства объекта. И когда приложение запросит данные в формате JSON, оно должно точно понимать, как будут организованы данные в ответе. Только в этом случае приложение сможет обработать ответ.
JSON-схема — это декларативное описание структуры объектов JSON. Схема содержит:
  • декларирование о том, что JSON является схемой,
  • название всех свойств объекта,
  • типы данных,
  • уровни вложенности объектов.
JSON-схему может прочитать человек, который знаком со стилем представления JSON, а также этот документ может «читать» программное обеспечение.
На что следует обращать внимание при анализе JSON-схемы:
  1. JSON-схема начинается с декларирования документа с помощью ключей:
    • $id — каждая схема обладает уникальным идентификатором,
    • $schema — указывает на ресурс, для которого была написана схема,
    • description — объясняет назначение данных, описываемых схемой,
    • "type": "object" — JSON-схема всегда описывает структуру объектов, поэтому указывается тип данных «объект».
Символ $ перед названием указывает на уникальность названия этого ключа в текущей схеме. Ключ с таким названием в этой схеме больше не встретится.
JSON
{
    "$id": "https://предметы-сервировки-стола.рф/товары/schema.json",
    "$schema": "https://предметы-сервировки-стола.рф/товары/schema",
    "description": "Возвращает описание товара",
    "type": "object",
        ...
        ...
        ...
}
  1. После декларирования схема описывает структуру объекта. Эта часть схемы отвечает на вопросы: «какая структура будет в теле ответа на запрос?» или «какая структура должна быть в теле запроса?». Структура JSON — это объект со свойством “properties”. Этот объект описывает все связки ключ:значение, которые присутствуют в объекте, а именно:
    • название ключа.
    • тип данных значения ключа.
    • если значение ключа представлено, как объект, состоящий из объектов, то указывается и структура вложенностей.
      Ниже представлен пример JSON-схемы описания товара. Объект “properties” состоит из шести связок ключ:значение.
    • Ключи “itemId”, “title” и “shape” имеют тип данных «строка».
    • Ключ “volume” имеет тип данных «число»
    • Ключ “material” может иметь множество значений, поэтому ему присвоен тип данных «массив». Массив, в свою очередь состоит из значений с типом данных «строка».
JSON
{
    "$id": "https://предметы-сервировки-стола.рф/товары/schema.json",
    "$schema": "https://предметы-сервировки-стола.рф/товары/schema",
    "description": "Возвращает описание товара",
    "type": "object",
    "properties": {
        "itemId": {
            "type": "string"
        },
        "title": {
            "type": "string"
        },
        "shape": {
            "type": "string"
        },
        "volume": {
            "type": "number"
        },
        "material": {
            "type": "array",
            "properties": {
                "type": "string"
            }
        },
        "fragile": {
            "type": "boolean"
        }
    }
}
  1. Свойства объектов могут быть обязательными и необязательными. По умолчанию все свойства, которые перечислены в объекте “properties” являются опциональными. То есть какие-то из свойств объекта могут присутствовать в ответе, а некоторые могут отсутствовать. Если свойства объекта являются обязательными, то эти свойства будут перечислены в виде значений ключа “required”.
  2. В схеме могут быть повторяющиеся части. Схема JSON может ссылаться на другие схемы. Например, вместо того, чтобы дублировать структуры объектов из других схем, можно просто указать ссылку на нужную часть схемы с другим идентификатором. Для обозначения ссылки используется ключ “$ref”. В значение ключа необходимо указать id схемы, на которую даётся ссылка. Если внутри схемы регулярно используется объект с одинаковой структурой, то можно указать ссылку на часть текущей схемы. Для этого также используется ключ $ref”, а значение будет начинаться с символа #. В примере ниже структура объекта “vendor” размещена в другой части той же схемы. Найти эту структуру можно по значению ключа. Символ # указывает на то, что искать нужно в текущем документе. А часть значения ключа /definitions/vendor указывает на расположение искомого объекта в схеме.
JSON
{
    "$id": "https://предметы-сервировки-стола.рф/товары/schema.json",
    "$schema": "https://предметы-сервировки-стола.рф/товары",
    "description": "Возвращает описание товара",
    "type": "object",
    "properties": {
        "itemId": {
            "type": "string"
        },
        "title": {
            "type": "string"
        },
        "shape": {
            "type": "string"
        },
        "volume": {
            "type": "number"
        },
        "material": {
            "type": "array",
            "properties": {
                "type": "string"
            }
        },
        "fragile": {
            "type": "boolean"
        },
        "vendors": {
            "$ref": "#/definitions/vendor"
        }
    },
        "required":["itemId", "title", "vendor"],
    "definitions": {
        "vendor": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "country": {
                    "type": "string"
                }
            }
        }
    }
}
Выберите в списке верные утверждения о назначении и особенностях использования JSON-схемы:

Подведём итоги

Стиль представления данных (Data Representation Style) — это набор синтаксических правил оформления данных, которыми обмениваются приложения, Наиболее распространёнными стилями являются JSON и XML.
JSON — нотация объектов JavaScript. JSON позволяет описывать объекты, которые содержат в себе набор данных.
Каждый объект в JSON состоит из множества наборов ключ:значение (Key:Value).
В JSON используются типы данных: строка, число, логический, null, массив и объект.
Для описания структуры объектов JSON используют JSON-схему. Схема содержит:
  • декларирование о том, что JSON является схемой,
  • название всех свойств объекта,
  • типы данных,
  • уровни вложенности объектов.
В следующем уроке вы познакомитесь с ещё одним стилем представления данных.