Откройте объекты API JSON в качестве параметров запроса

1. Обзор

В этом уроке мы узнаем, как работать с объектами JSON в качестве параметров запроса с помощью OpenAPI .

2. Параметры запроса в открытом API 2

OpenAPI 2 не поддерживает объекты в качестве параметров запроса ; поддерживаются только примитивные значения и массивы примитивов.

Из-за этого мы вместо этого захотим определить наш параметр JSON как строку .

Чтобы увидеть это в действии, давайте определим параметр params как string , хотя мы будем анализировать его как JSON в нашем бэкэнде:

swagger: "2.0"
...
paths:
  /tickets:
    get:
      tags:
      - "tickets"
      summary: "Send an JSON Object as a query param"
      parameters:
      - name: "params"
        in: "path"
        description: "{\"type\":\"foo\",\"color\":\"green\"}"
        required: true
        type: "string"

Таким образом, вместо:

GET http://localhost:8080/api/tickets?type=foo&color=green

мы сделаем это:

GET http://localhost:8080/api/tickets?params={"type":"foo","color":"green"}

3. Параметры запроса в OpenAPI 3

Open API 3 вводит поддержку объектов в качестве параметров запроса.

Чтобы указать параметр JSON, нам нужно добавить в наше определение раздел content , который включает тип MIME и схему:

openapi: 3.0.1
...
paths:
  /tickets:
    get:
      tags:
      - tickets
      summary: Send an JSON Object as a query param
      parameters:
      - name: params
        in: query
        description: '{"type":"foo","color":"green"}'
        required: true
        schema:
          type: object
          properties:
            type:
              type: "string"
            color:
              type: "string"

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

GET http://localhost:8080/api/tickets?params[type]=foo&params[color]=green

И, на самом деле, это все еще может выглядеть так:

GET http://localhost:8080/api/tickets?params={"type":"foo","color":"green"}

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

Со вторым вариантом мы торгуем этим для большего контроля над бэкендом, а также для совместимости с открытым API 2.

4. Кодирование URL-адресов

Важно отметить, что при принятии этого решения о передаче параметров запроса в качестве объекта JSON мы захотим кодировать URL-адрес параметра для обеспечения безопасной транспортировки.

Итак, чтобы отправить следующий URL-адрес:

GET /tickets?params={"type":"foo","color":"green"}

На самом деле мы бы так и сделали:

GET /tickets?params=%7B%22type%22%3A%22foo%22%2C%22color%22%3A%22green%22%7D

5. Ограничения

Кроме того, давайте иметь в виду ограничения передачи объекта JSON в виде набора параметров запроса:

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

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

Кроме того, один параметр запроса может содержать не более 2048 символов. Конечно, мы все можем представить себе сценарии, в которых наши объекты JSON больше, чем это. Практически говоря, кодировка URL-адреса нашей строки JSON фактически ограничит нас примерно 1000 символами для нашей полезной нагрузки.

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

На самом деле, GET или POST оба поддерживают это. Одна из причин отправки тела через GET заключается в сохранении семантики RESTful нашего API.

Конечно, это немного необычно и не повсеместно поддерживается. Например, некоторые библиотеки HTTP JavaScript не позволяют GET-запросам иметь тело запроса.

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

6. Заключение

Подводя итог, в этой статье мы узнали, как указать объекты JSON в качестве параметров запроса с помощью OpenAPI. Затем мы наблюдали некоторые последствия для бэкенда.

Полные определения открытого API для этих примеров доступны на GitHub .