Top Menu

Jump to content
  • 1.2 Public APIs
    • View all projects
Home
    • News
    • Getting started
    • Video
    • Welcome to OpenProject

      Get an overview

      Get a quick overview of project management and team collaboration with OpenProject.

    • Help and support
    • Upgrade to Enterprise Edition
    • User guides
    • Shortcuts
    • Community forum
    • Professional support

    • Additional resources
    • OpenProject blog
    • Release notes
    • Report a bug
    • Development roadmap
    • Add and edit translations
    • API documentation
  • Sign in
      Create a new account
      Forgot your password?

      Welcome to OpenProject

      Create a new account



      Must be at least 6 characters long.

      Welcome to OpenProject

      Create a new account



      Must be at least 6 characters long.

Side Menu

  • Overview
  • Wiki
You are here:
  • Home
  • 1.2 Public APIs
  • CRUDEX-API builder v1.0.x

Content

CRUDEX-API builder v1.0.x

  • More
    • Table of Contents

¶

  1. Введение
    • 1.1 Назначение модуля
    • 1.2 Общие принципы
  2. Формирование "url" запроса
    • 2.1 Структура
    • 2.2 Строка параметров
      • 2.2.1 Формат
      • 2.2.2 Именования полей
      • 2.2.3 Условия
      • 2.2.4 Режимы
      • 2.2.5 Сортировка
  3. Примеры запросов по типам
    • 3.1 Создание
    • 3.2 Чтение
    • 3.3 Изменение
    • 3.4 Замена
    • 3.5 Удаление
    • 3.6 Выполнение
  4. Формат ответа
    • 4.1 Структура

1 Введение¶

| 1.1 Назначение модуля | вверх¶

  • Предоставление интерфейса взаимодействия с DataCore 3;

| 1.2 Общие принципы | вверх¶

  • Взаимодействие с DataCore 3 построено на шаблонах. Шаблон - универсальное представление набора данных. Шаблон может равнятся одной таблице в базе, может равнятся нескольким. Основное преимущество шаблона - он абстрагирует данные от механизма их хранения. Пример - есть шаблон "пользователь", у него есть имя и фамилия, которые хранятся в одной таблице, есть адрес, который хранится в другой таблице, но клиенту эти данные приходят одним набором.
  • Шаблоны имеют свой уникальный идентификатор (номер);
  • Для произведения манипуляций с данными в базе нужно отправить запрос соответствующего типа на API сервер с указанием номера шаблона и параметров запроса;
  • Поддерживаються следующие операции над шаблонами котрым соответствуют типы запросов:
    операция тип запроса описание
    создание POST в базе создаеться новая запись по указанному шаблону
    чтение GET из базы получаем записи, либо все, либо согласно указанным условиям, по указанному шаблону
    редактирование PUT в базе редактируется запись по указанному условию
    замена PATCH в базе осуществляеться замена либо создание записи если она отстутсвует
    выполнение MOVE в базе выполняеться процедура, соответствующая шаблону
    удаление DELETE в базе удаляется запись по указанному шаблону и условию
  • К шаблонам могут быть разрешены как все типы запросов так и только некоторые;

2 Формирование "url" запроса¶

| 2.1 Структура | вверх¶

<protokol>://<host>[:<port>]/<version of api>/<template id>?token[<parameters string>]

параметр присутствие описание пример
protokol обязательно протокол передачи данных http, https
host обязательно доменное имя или ip адрес ресурса localhost, 127.0.0.1
port опционально порт на котором работает api, если не указан то для http по умолчанию используется 80, для https 443 3333, 5555
version of api обязательно используется для идентификации алгоритма обработки входящих запросов /api.v1
template id обязательно номер шаблона DataCore 3 к которому идет обращение /2018
parameters string обязательно описывается в отдельном разделе ниже token=123456789&fields=name&conditions[name][equal]=234&

| 2.2 Строка параметров | вверх¶

| 2.2.1 Формат | вверх¶

  • Строка параметров состоит из пар ключ значение, в отдельных случаях у ключей может не быть значения (например token до прохождения аутентификации);
  • Разделителем между параметрами являеться знак &;
  • Значения ключей указываються без кавычек;
  • Чтобы передать пробел в каком то значении его следует заменить на +, например &conditions[name][equal]=taras+kuprunets;
  • Принцип постоения сторки параметров cледующий:

token=value[&fields=name...][&conditions[fildName][conditionType]=value...][&modes=value...][&limit[offset]=0&limit[rowCount]=10]

параметр присутствие описание пример
?token обязательно служит для идентификации клиента, передается всегда. Если токен отсутствует (например до авторизации) передается параметр без значения token, token=123456789
&fields опционально служит для указания имен полей шаблона по которым производится операция (чтение либо изменение) &fields=name&fields=surname
&conditions опционально cлужит для указания параметров выборки записейк к которым применяется операция &conditions[name][equal]=taras&conditions[surname][equal]=kuprunets
&modes опционально служит для указания нестандартного поведения либо расширения возможностей выполнения запроса &modes=testing&modes=noPrepare
&limit опционально служит для задания количества записей, которsе ожиаються от сервера, и номер первой записи от которой начинать отсчет &limit[offset]=0&limit[rowCount]=10

| 2.2.2 Именования полей | вверх¶

  • Передаються в формате fields=fieldMane. Если нужно передать несколько имен полей - передаеться несколько значений идентификатора fields;
  • Имена полей передаються когда:
    • Хотим получить не всю информацию по шаблону, а только некоторые поля. Пример, шаблон "пользователь" сотоит из 20 полей (имя, фамилия, аватар, адрес, телефон, имейл и т д), в текущем запросе нам нужно лишь имя и фамилия, тогда нужно явно передать названия этих полей;
    • Нужно отредактировать заданные поля записей;

| 2.2.3 Условия | вверх¶

  • Передаються в формате conditions[fildName][conditionType]=value. Если нужно передать несколько имен полей - передаеться несколько значений идентификатора conditions;
  • Служат для указания параметров по которым та или иная операция применяется к записям шаблона;
  • Поддерживаються типы условий:
тип значение пример
equal равно conditions[name][equal]=taras
notEqual не равно conditions[name][notEqual]=taras
greatest больше conditions[age][greatest]=30
greatestEqual больше или равно conditions[age][greatestEqual]=30
less меньше conditions[age][equal]=30
lessEqual меньше или равно conditions[age][equal]=30
isNull равно или не равно NULL (в зависимости от передаваемого значения) conditions[name][isNull]=true conditions[name][isNull]=false
in находится в перечислении, разделителем значений является запятая conditions[name][in]=0,1,2,3,4
notIn не находится в перечислении, разделителем значений является запятая conditions[name][notIn]=0,1,2,3,4
like содержит conditions[name][like]=ara
notLike не содержит conditions[name][notLike]=ras

| 2.2.4 Режимы | вверх¶

  • Передаются в формате modes=value. Если нужно передать несколько режимов - передается несколько значений идентификатора modes;
  • Используются если нужно задать нестандартное поведение
  • На данный момент доступны следующие режимы:
тип значение описание пример
тестовый testing вместе с данными запроса мы в ответе получаем в секции debug пакет сгенерированный для выполнения на севрере &modes=testing
не обработанный noPrepared база данных возвращает ответ в виде двух масивов - масив имен полей и масив масивов значений, сервер преобразовывает ответ в масив обектов имя поля - значение поля, если стоит режим без предварительно обработки - сервер не будет выполнять это преобразование &modes=noPrepared

| 2.2.5 Сортировка| вверх¶

  • Передается в формате sort[fieldName]=sortType. Если нужно передать по нескольким полям - передается несколько значений идентификатора sort;
  • Используются если нужно получить определенным образом отсортированные данные
  • На данный момент доступны следующие режимы сортировки:
тип значение пример
по возрастанию desc &sort[dtClient]=desc
по убыванию asc &sort[dtClient]=asc

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

| 3.1 Создание | вверх¶

  • Создание записей производится с помощью метода POST
  • В строке параметров должны быть переданы имена полей по которым передаються данные в теле запроса;
  • Те поля, которые не упоминаються в fields, будут созданы со значениями поо умолчанию;
    POST http://localhost:8081/api.v1/2018?token=123456789&fields=name&fields=surname
    Content-Type: application/json
    [
        ["taras", "kuprunets"],
        ["andrey", "sakhno"]
    ]

| 3.2 Чтение | вверх¶

  • Чтение записей производится с помощью метода GET;
  • При чтении могут передаваться лимиты в строке параметров если лимиты не были переданы вернется максимально разрешенное количествоо записей. Чтобы удостоверится что выбраны все записи нужно сверить количество зписей со значением полея rowCount в метаданных пакета. Если оно больше чем получено значений необходимо віполнить еще один запрос но уже с указанием лимитов.
  • При чтении могут передаваться условия выборки в строке параметров;
    GET http://localhost:8081/api.v1/2018?token=123456789

| 3.3 Изменение | вверх¶

  • Изменение записей производиться с помощью метода PUT;
  • В строке параметров необходимо передать имена полей которые подлежать изменению;
  • В теле запроса необхдимо передать значения полей выдерживая порядок указания имен полей в строке параметров.
  • При изменении следует указать условия по которым будут однозначно идентифицированы записи которые подлежат изменению, если условия указаны не будут - произведется изменение всех записей указанного шаблона;
    PUT http://localhost:8081/api.v1/2018?token=123456789&fields=name&fields=surname&conditions[objectId][equal]=1
    Content-Type: application/json
    [
        ["taras", "kuprunets"]
    ]

| 3.4 Замена | вверх¶

  • Замена записей производиться с помощью метода PATCH;
  • В строке параметров необходимо передать имена полей которые подлежать замене таким же образом следует передать название поля ключа для идентификации;
  • В теле запроса необхдимо передать значения полей выдерживая порядок указания имен полей в строке параметров а так же значение ключей.
    PATCH http://localhost:8081/api.v1/2018?token=123456789&fields=name&fields=surname
    Content-Type: application/json
    [
        ["taras", "kuprunets"],
        ["andrey", "sakhno"]
    ]

| 3.5 Удаление | вверх¶

  • Удаление записей производиться с помощью метода DELETE;
  • При elfktybb следует указать условия по которым будут однозначно идентифицированы записи которые подлежат удалению, если условия указаны не будут - произведется удаление всех записей указанного шаблона;
    DELETE http://localhost:8081/api.v1/2018?token=123456789&conditions[objectId][equal]=100

| 3.6 Выполнение | вверх¶

  • Существуют операции которые выходят за рамки простого создания/редактирования/удаления данных, к этим операциям можно отнести процес авторизации, сложных добавлений данных или комплексных созданий записей, требующих предварительной обработки. Для этих целей предусмотрен специальный механизм который позволяет обратится к шаблону как к функции, дав команду на ее выполнение.
  • Выполнение шаблонов производиться с помощью метода MOVE;
  • В теле запроса необхдимо передать значения входных параметров, какие конкретно параметры подлежат передаче зависит от конретного шаблона и будут описаны в отдельных документах, которые будут описывать конкретные раелизации API.
    MOVE http://localhost:8081/api.v1/2018?token=123456789
    Content-Type: application/json
    [
        ["firstParam", "secondParam"]
    ]

4 Формат ответа¶

| 4.1 Структура | вверх¶

  • Каждый ответ имеет статус по которому можно определить успешность/неуспешность выполнения операции;
  • Статусы ответов - стандарнтные статусы описанные в протоколе http http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml ;
  • Сервер возвращает ответ в JSON формате;
    HTTP/1.1 200 Ok
    Content-Type: application/json
    {
        "data": [
            {
                "metadata": {
                    "templateId": number,
                    "rowCount": number
                },
                "data": {
                    "fild1": "value1",
                    ...
                    "fildN": "valueN" 
                }
            }, {
                "metadata": {
                    "templateId": number,
                    "rowCount": number
                },
                "data": {
                    "fild1": "value1",
                    ...
                    "fildN": "valueN" 
                }
            } 
        ],
        "debug"?: {
            "package": "JSONString" 
        }
    }
 
 
Loading...
Powered by OpenProject