Skip to Content
РазработчикамИспользование REST API

Использование REST API

Обзор API

REST API компонента primoart-api предоставляет следующие функциональные возможности:

  • Выполнение CRUD операций для модели данных.

  • Выполнение запросов для поиска сущностей в модели данных.

  • Выполнение запросов для получения связанных объектов согласно модели данных.

  • Получение информации из базы данных в произвольных разрезах.

Названия конечных точек (endpoints) формируются на основе схемы данных и унифицированы с названиями таблиц базы данных, если это не нарушает логику компонента.

ℹ️

Полный перечень методов представлен в Swagger.

Дополнительные параметры запроса

Ко всем запросам поиска могут быть применены дополнительные параметры:

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

  • filters: Массив правил фильтрации, объединенных логическим И.

    • Поддерживаемые операторы и их синтаксис:

      • all: Объединение фильтров логическим И;

      • any: Объединение фильтров логическим ИЛИ;

      • is: точное совпадение;

      • isNot: отрицание точного совпадения;

      • gt: больше чем;

      • lt: меньше чем;

      • gte: больше или равно;

      • lte: меньше или равно;

      • contains: содержит;

      • notContains: не содержит;

      • startsWith: начинается с;

      • endsWith: заканчивается на;

      • inTheRange: в диапазоне значений;

      • before: до указанной даты;

      • after: после указанной даты;

      • from: начиная с указанной даты. Поддерживаются метки времени и JIRA Time;

      • to: заканчивая указанной датой. Поддерживаются метки времени и JIRA Time;

      • inTheLast: за предшествующий временной интервал в формате JIRA Time;

      • inTheNext: в течение следующего временного интервала в формате JIRA Time.

  • sort: Наименование поля, по которому выполняется сортировка;

  • order: Порядок выдачи asc / desc;

  • limit: Количество записей, возвращаемых с ответом.

Описание ключей ответа

  • status: Результат выполнения запроса (success/fail);

  • took: Время выполнения запроса в миллисекундах;

  • received: Количество полученных записей;

  • created: Количество созданных записей;

  • updated: Количество обновленных записей;

  • deleted: Количество удаленных записей;

  • results: Массив полученных/обновленных/сохраненных записей.

Примеры использования операторов

all: Объединение фильтров логическим И

Задача: Найти все записи, у которых статус active и возраст больше 30.

{
  "filters": [
    {
      "all": [
        {
          "is": {
            "status": "active"
          }
        },
        {
          "gt": {
            "age": 30
          }
        }
      ]
    }
  ]
}

any: Объединение фильтров логическим ИЛИ

Задача: Найти все записи, у которых статус active или возраст больше 30.

{
  "filters": [
    {
      "any": [
        {
          "is": {
            "status": "active"
          }
        },
        {
          "gt": {
            "age": 30
          }
        }
      ]
    }
  ]
}

is: точное совпадение

Задача: Найти все записи, у которых статус active.

{
  "filters": [
    {
      "is": {
        "status": "active"
      }
    }
  ]
}

isNot: отрицание точного совпадения

Задача: Найти все записи, у которых статус не inactive.

{
  "filters": [
    {
      "isNot": {
        "status": "inactive"
      }
    }
  ]
}

gt: больше чем

Задача: Найти все записи, у которых возраст больше 30.

{
  "filters": [
    {
      "gt": {
        "age": 30
      }
    }
  ]
}

lt: меньше чем

Задача: Найти все записи, у которых возраст меньше 30.

{
  "filters": [
    {
      "lt": {
        "age": 30
      }
    }
  ]
}

gte: больше или равно

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

{
  "filters": [
    {
      "gte": {
        "age": 30
      }
    }
  ]
}

lte: меньше или равно

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

{
  "filters": [
    {
      "lte": {
        "age": 30
      }
    }
  ]
}

contains: содержит

Задача: Найти все записи, у которых описание содержит подстроку “urgent”.

{
  "filters": [
    {
      "contains": {
        "description": "urgent"
      }
    }
  ]
}

notContains: не содержит

Задача: Найти все записи, у которых описание не содержит подстроку “urgent”.

{
  "filters": [
    {
      "notContains": {
        "description": "urgent"
      }
    }
  ]
}

startsWith: начинается с

Задача: Найти все записи, у которых имя начинается с “John”.

{
  "filters": [
    {
      "startsWith": {
        "name": "John"
      }
    }
  ]
}

endsWith: заканчивается на

Задача: Найти все записи, у которых имя заканчивается на “Doe”.

{
  "filters": [
    {
      "endsWith": {
        "name": "Doe"
      }
    }
  ]
}

inTheRange: в диапазоне значений

Задача: Найти все записи, у которых возраст находится в диапазоне от 20 до 30 включительно.

{
  "filters": [
    {
      "inTheRange": {
        "age": [20, 30]
      }
    }
  ]
}

before: до указанной даты

Задача: Найти все записи, созданные до 1 января 2024 года.

{
  "filters": [
    {
      "before": {
        "created_at": "2024-01-01T00:00:00Z"
      }
    }
  ]
}

after: после указанной даты

Задача: Найти все записи, созданные после 1 января 2024 года.

{
  "filters": [
    {
      "after": {
        "created_at": "2024-01-01T00:00:00Z"
      }
    }
  ]
}

from: начиная с указанной даты (метка времени)

Задача: Найти все записи, созданные начиная с 1 января 2024 года.

{
  "filters": [
    {
      "from": {
        "created_at": "2024-01-01T00:00:00Z"
      }
    }
  ]
}

from: начиная с указанной даты (JIRA Time)

Задача: Найти все записи, созданные начиная с последнего месяца.

{
  "filters": [
    {
      "from": {
        "created_at": "-1M"
      }
    }
  ]
}

to: заканчивая указанной датой (метка времени)

Задача: Найти все записи, созданные до 1 января 2025 года.

{
  "filters": [
    {
      "to": {
        "created_at": "2025-01-01T00:00:00Z"
      }
    }
  ]
}

to: заканчивая указанной датой (JIRA Time)

Задача: Найти все записи, созданные до настоящего момента.

{
  "filters": [
    {
      "to": {
        "created_at": "now"
      }
    }
  ]
}

inTheLast: за предшествующий временной интервал (JIRA Time)

Задача: Найти все записи, обновленные за последние 30 дней.

{
  "filters": [
    {
      "inTheLast": {
        "updated_at": "30d"
      }
    }
  ]
}

inTheNext: в течение следующего временного интервала (JIRA Time)

**Задача: Найти все записи, которые будут актуальны в течение следующего месяца.

{
  "filters": [
    {
      "inTheNext": {
        "valid_until": "1M"
      }
    }
  ]
}

Примеры использования операторов в запросах

Получить все записи с фильтром is и gt:

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "is": {
        "name": "Location A"
      }
    },
    {
      "gt": {
        "sla": 95.0
      }
    }
  ]
}
'

Получить все записи с фильтром any для логического ИЛИ:

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "any": [
        {
          "is": {
            "name": "Location A"
          }
        },
        {
          "gt": {
            "sla": 95.0
          }
        }
      ]
    }
  ]
}
'

Получить все записи, созданные начиная с указанной даты (метка времени):

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "from": {
        "created_at": "2024-01-01T00:00:00Z"
      }
    }
  ]
}
'

Получить все записи, созданные начиная с последнего месяца (JIRA Time):

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "from": {
        "created_at": "-1M"
      }
    }
  ]
}
'

Примеры объединения операторов фильтрации

Использование оператора AND

Задача: Найти все записи, у которых статус active и возраст больше 30.

{
  "filters": [
    {
      "is": {
        "status": "active"
      }
    },
    {
      "gt": {
        "age": 30
      }
    }
  ]
}

Этот запрос выберет записи, у которых значение поля status равно “active” и значение поля age больше 30.

Использование оператора OR

Задача: Найти все записи, у которых статус active или возраст больше 30.

{
  "filters": [
    {
      "any": [
        {
          "is": {
            "status": "active"
          }
        },
        {
          "gt": {
            "age": 30
          }
        }
      ]
    }
  ]
}

Этот запрос выберет записи, у которых значение поля status равно “active” или значение поля age больше 30.

Комбинация операторов AND и OR

Задача: Найти все записи, у которых статус active и (возраст больше 30 или рейтинг выше 4).

{
  "filters": [
    {
      "is": {
        "status": "active"
      }
    },
    {
      "any": [
        {
          "gt": {
            "age": 30
          }
        },
        {
          "gt": {
            "rating": 4
          }
        }
      ]
    }
  ]
}

Этот запрос выберет записи, у которых значение поля status равно “active” и (значение поля age больше 30 или значение поля rating больше 4).

Использование оператора NOT

Задача: Найти все записи, у которых статус не inactive и возраст больше 30.

{
  "filters": [
    {
      "isNot": {
        "status": "inactive"
      }
    },
    {
      "gt": {
        "age": 30
      }
    }
  ]
}

Этот запрос выберет записи, у которых значение поля status не равно “inactive” и значение поля age больше 30.

Сложное условие с AND, OR, и NOT

Задача: Найти все записи, у которых (статус active и возраст больше 30) или (рейтинг выше 4 и не содержат слово “urgent” в описании).

{
  "filters": [
    {
      "any": [
        {
          "all": [
            {
              "is": {
                "status": "active"
              }
            },
            {
              "gt": {
                "age": 30
              }
            }
          ]
        },
        {
          "all": [
            {
              "gt": {
                "rating": 4
              }
            },
            {
              "notContains": {
                "description": "urgent"
              }
            }
          ]
        }
      ]
    }
  ]
}

Этот запрос выберет записи, у которых (значение поля status равно “active” и значение поля age больше 30) или (значение поля rating больше 4 и поле description не содержит слово “urgent”).

Примеры запросов с объединением операторов

Пример 1: Получить все записи с условием AND

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "is": {
        "status": "active"
      }
    },
    {
      "gt": {
        "age": 30
      }
    }
  ]
}
'

Пример 2: Получить все записи с условием OR

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "any": [
        {
          "is": {
            "status": "active"
          }
        },
        {
          "gt": {
            "age": 30
          }
        }
      ]
    }
  ]
}
'

Пример 3: Получить все записи с комбинацией AND и OR

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "is": {
        "status": "active"
      }
    },
    {
      "any": [
        {
          "gt": {
            "age": 30
          }
        },
        {
          "gt": {
            "rating": 4
          }
        }
      ]
    }
  ]
}
'

Пример 4: Получить все записи с условием NOT

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "isNot": {
        "status": "inactive"
      }
    },
    {
      "gt": {
        "age": 30
      }
    }
  ]
}
'

Пример 5: Получить все записи с комплексным условием AND, OR, и NOT

curl -X POST "http://localhost:8000/api/v1/locations/search" -H "Content-Type: application/json" -d '
{
  "filters": [
    {
      "any": [
        {
          "all": [
            {
              "is": {
                "status": "active"
              }
            },
            {
              "gt": {
                "age": 30
              }
            }
          ]
        },
        {
          "all": [
            {
              "gt": {
                "rating": 4
              }
            },
            {
              "notContains": {
                "description": "urgent"
              }
            }
          ]
        }
      ]
    }
  ]
}
'
Last updated on
Описание разделаРазработка транзакции для STM-агента Lite (Playwright)