OpenPIM API

Введение

Что такое API

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

При помощи API можно выполнить ряд операций, связанных с управлением информацией о продуктах. СТановится возможным получение информации о продуктах, добавление новых продуктов, управление категориями и атрибутами и тому подобное.

Что такое GraphQL

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

Cхемы GraphQL, которые поддерживаются OpenPIM находятся по этой ссылке.

Преимущества GraphQL включают в себя:

Гибкость запросов: В отличие от традиционных REST API, где каждый конечный пункт имеет фиксированную структуру и возвращает предопределенные данные, в GraphQL клиент может запрашивать только те данные, которые ему нужны. Это позволяет избежать проблемы "over-fetching" (избыточное получение данных) и "under-fetching" (недостаточное получение данных).
Однородный интерфейс: В GraphQL все запросы выглядят одинаково, независимо от того, что они запрашивают. Запросы представляют собой древовидную структуру, где клиент указывает только те поля и связи, которые его интересуют. Это делает API более понятным и удобным для работы.
Связи между данными: GraphQL позволяет описывать сложные связи между данными и выполнять глубокие запросы, чтобы получить данные из нескольких связанных объектов одним запросом. Это упрощает работу с данными, которые имеют сложную структуру или взаимосвязи.
Инструменты разработчика: Существует множество инструментов для работы с GraphQL, включая инструменты для разработки клиентских приложений, инструменты для отладки запросов, генераторы документации и многое другое. Это делает процесс разработки и отладки API более эффективным.

Примеры запросов

Запрос типа Query

В GraphQL существует два типа запросов: поиск данных и изменение данных.

Название типа запроса - это ключевое слово, которое определяет тип запроса. В данном случае, это Query, что означает, что эти операции предназначены для чтения данных. Ниже представлен пример.

    type Query {
        search(requests: [SearchRequest]!): SearchResponses!
        getSearchByIdentifier(identifier: String!): SavedSearch
        getSearches(onlyMy: Boolean!): [SavedSearch]!
        getColumns(onlyMy: Boolean!): [SavedColumns]!
        getColumnsByIdentifier(identifier: String!): SavedColumns
    }

1
2
3
4
5
6
7

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

search - поиск по запросам с возвратом ответов.
getSearchByIdentifier - получение сохраненного поиска по его идентификатору.
getSearches - получение списка сохраненных поисков.
getColumns - получение списка сохраненных колонок.
getColumnsByIdentifier - получение сохраненных колонок по их идентификатору.

Некоторые поля могут принимать аргументы, которые используются для настройки запроса. Например, getSearchByIdentifier принимает аргумент identifier, который указывает идентификатор сохраненного поиска, который нужно получить.

Возвращаемые типы (Return Types): Каждое поле имеет определенный тип данных, который он возвращает. Например, getSearches возвращает массив объектов типа SavedSearch.

Восклицательный знак (!): В GraphQL восклицательный знак обозначает обязательность поля или типа данных. Например, [SavedSearch]! означает, что возвращаемый список сохраненных поисков не может быть пустым.

Для получения данных о каком-либо товаре необходимо составить Query-запрос. Пример подобного запроса представлен ниже:

    query { search(
        requests: [
            {
                entity: ITEM, 
                offset: 0, 
                limit: 10,
                where: {typeIdentifier: "item",values: {size: {OP_gt: "118"}}},
                order:[["id", "asc"]]
            }
        ]
    ){
        responses {
            ... on ItemsSearchResponse {
                count
                rows {
                    identifier
                    name
                    values
                }
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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

entity - определяет тип сущности, по которой будет выполняться поиск. В данном случае, указано значение ITEM, что, вероятно, указывает на поиск по элементам (товарам) в системе.

offset - определяет смещение (индекс), с которого начинается выборка результатов поиска. В данном случае, указано значение 0, что означает, что выборка начинается с самого начала.

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

where - определяет условия фильтрации результатов поиска. В данном случае, указано условие по типу (typeIdentifier) и значению размера (size) элемента. Данное поле предоставляет возможность для поиска элементов по любому признаку, указанных в системе, будь это название, идентификатор или значение одного или нескольких атрибутов.

typeIdentifier: Определяет тип идентификатора, по которому выполняется фильтрация. В данном случае, указано значение "item".
values: Содержит значения для фильтрации. В данном случае, указано значение размера (size), которое сравнивается с оператором OP_gt (больше чем) и значением "118".

Более детально смотрите в приложении Язык запросов

order - определяет порядок сортировки результатов. В данном случае, указано, что результаты должны быть отсортированы в порядке по возрастанию (asc) идентификатора (id) элемента.

Поле responses в данном запросе определяет ожидаемую структуру данных, которая будет возвращена в ответ на выполнение запроса. Здесь используется оператор ... on, который позволяет указать тип ожидаемого ответа. В данном случае, ожидается объект типа ItemsSearchResponse. Давайте подробнее рассмотрим каждое поле в объекте responses:

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

rows - это поле содержит массив объектов, каждый из которых представляет найденный элемент. Каждый объект содержит следующие поля:

identifier: Идентификатор элемента. Это может быть уникальный идентификатор или какой-то другой идентификатор, который позволяет однозначно идентифицировать элемент.
name: Название элемента. Это поле содержит название или заголовок элемента, которое может использоваться для его отображения.
values: Значения элемента. Это поле содержит дополнительные значения или характеристики элемента. Например, это может быть набор атрибутов или свойств элемента, таких как цена, размер, цвет и т. д.

Каждое поле в объекте rows представляет информацию об одном найденном элементе.

По итогу этого запроса программа выведет в консоль информацию о продукте, у которого атрибут "size" имеет значение, большее 118.

Также имеется возможность запросить связи, присущие товарам. В примере ниже представлен запрос на получение связей у одного конкретного товара. Для этого используется тип сущности ITEM_RELATION.

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

    query { 
        search(
        requests: [
            {
            entity: ITEM_RELATION, 
                offset: 0, 
                limit: 10,
                where: {itemIdentifier: "america_standard_16a_germany_socket_with_italian_socket_combination"}
            }   
        ]
    ){
        responses {
        ... on SearchItemRelationResponse {
            rows {
                    identifier
                    targetId
                    relationIdentifier
                    relationId
                }
            } 
        }               
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

В результате этого запроса ожидается получение:

identifier: Идентификатор связи между элементами.
targetId: Идентификатор целевого элемента связи.
relationIdentifier: Идентификатор связи.
relationId: Идентификатор связанного элемента.

Ответом получим список имеющихся связей.

Запрос типа Import

Рассмотрим пример запроса на изменение данных. В качестве ключевого слова здесь будет выступать mutation. В данном примере рассматривается изменение значения атрибута "color" для элементов, у которых значение "color" равно 4.

Сначала применим запрос поиска наподобие примера, описанного выше.

    query { search(
        requests: [
            {
                entity: ITEM,
                offset: 0,
                limit: 1000,
                where: {values: {color: 4}},
                order: []
            }]
        ) {
        responses {
            ... on ItemsSearchResponse {
                count
                rows {
                  identifier
                  name
                  values
                }
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

В качестве ответа получили массив элементов, у которых значение "color" равно 4. Изменение значений будут происходить с теми товарами, идентификаторы которых будут подставлены в следующем запросе.

Далее составим запрос с применением mutation.

    mutation{ import(
            config:{
                mode: UPDATE_ONLY
                errors: PROCESS_WARN
            },
            items:[
                {
                    identifier: "<идентификатор продукта что обновляем>",
                    values: {color: 1}
                }
            ]
            ) {
            items {
              result
              id
              errors { code message }
              warnings { code message }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import - Название мутации. В данном случае, это имя операции.

config - Объект, содержащий настройки для импорта данных.

mode - Режим импорта данных. В данном случае, режим обновления (UPDATE_ONLY), который означает, что только существующие данные будут обновлены, новые данные не будут добавлены. Некоторые альтернативные режимы выглядят так:

CREATE_ONLY - создавать только новые элементы. Если элемент уже существует, возникает ошибка
CREATE_UPDATE - создавать новые элементы и обновлять существующие. Если элемент существует, он будет обновлен, иначе будет создан новый
DELETE_ONLY - удалять элементы. Этот режим используется для удаления данных
APPEND - добавлять данные к существующим элементам, если это применимо

errors - Обработка ошибок. Здесь указано, что при возникновении ошибок следует продолжить обработку (PROCESS_WARN).

items - массив элементов, которые будут импортированы.

identifier - идентификатор элемента. Для внесения изменений будут использоваться идентификаторы, полученные при поиске товаров, подходящих под установленное условие. Это необходимо, чтобы в цикле пройти по всем значениям, полученным из запроса-поиска.
values - объект, содержащий значения, которые нужно обновить у элемента.
color - значение цвета. В данном случае, установлено значение 1.

Таким образом, после выполнения вышеописанных запросов в в системе произойдёт изменение значений атрибута "color". Там, где раньше стояло значение "4", теперь будет проставлено значение "1".

Примеры - Postman

Это популярный инструмент для разработки и тестирования API. Он предоставляет удобный интерфейс для создания, отправки и отладки HTTP-запросов, а также для автоматизации тестирования API.

Ниже представлена коллекция Postman, в которой содержатся некоторые типы зыпросов, описанные выше.

коллекция запросов Postman.

Примеры - Node JS

Проект на node.js который использует API.

В прикреплённом архиве находится пример составленного с помощью Node JS запроса. С подробным описанием Вы можете ознакомииться в файле README.txt, находящимся в архиве. Представленный код делает запрос на изменение с помощью "mutation" всех элементов, у которых значение атрибута "size" равно "118". Таким образом, при нахождении товара, удовлетворяющего условиям, в атрибуте "voltage" элемент "-" будет изменён на "~".

Файл server.js содержит функции, связанные с общением с сервером и аутентификацией пользователя для GraphQL-сервера.

Файл main.js демонстрирует использование функций, экспортированных из server.js, для выполнения определенных задач:

Аутентификация пользователя
Поиск элемента
Обновление элемента

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

Примеры - Python

Проект на pyton который использует API.

В архиве представлен пример написанного на Python запроса. С подробным описанием Вы можете ознакомииться в файле README.txt, находящимся в архиве. В данных примерах производится поиск элементов по атрибуту "color" и изменение значения данного атрибута, при выполнении условия.

Файл search.py содержит функции для поиска элементов на сервере GraphQL. Он включает следующие основные компоненты:

Запрос на поиск
Отправка запроса
Обработка ответа

Файл mutation.py содержит функции для выполнения мутаций на сервере GraphQL. Он включает следующие основные компоненты:

Формирование мутации
Отправка запроса
Обработка ответа

Оба файла предоставляют удобные интерфейсы для выполнения поиска и мутаций на сервере GraphQL, облегчая взаимодействие с данными на сервере и обновление их через API.

# OpenPIM API

# Введение

# Что такое API

# Что такое GraphQL

# Примеры запросов

# Запрос типа Query

# Запрос типа Import

# Примеры - Postman

# Примеры - Node JS

# Примеры - Python