Requality

h1. APIForNG

По текущей модели предполагается использование следующих методов:

Для всех методов по умолчанию используется один заголовочный параметр

Authorization со значением Bearer 36AC0A0F7F271314B72986EB54DB2343

1.Получение списка проектов (updated 1.4)

Method:

GET

Path:

http://localhost:9988/projects

Без дополнительных параметров.

Возвращает пары "имя хранимое: имя представления"

Пример "some-local-project:project". При этом первое используется для обращения к определенному проекту, в том числе при помощи API вызовов, а второе - для ссылок на артефакты проекта в других проектах. Например, так можно представить другой проек в котором будет ссылка вида project::Requirements.

Пример выдачи

<pre><code class="javascript">

{

  "success" : true,

  "result" : {

    "projects" : [ "Example":"Example", "з1":"з1", "someos-arch":"arch", "somestpo":"stpo"],

    "count" : 4

  }

}

</code></pre>

2. Получение содержимого проекта(иерархия), для expandable - ограниченное 1м уровнем 

Method:

GET

Path:

http://localhost:9988/projects/{arch}[/expandable]

Здесь {arch} - имя проекта, на данный момент регистрозависимо

Без дополнительных параметров

Пример выдачи

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "name": "arch",

    "nodes": [

      {

        "uuid": "243f4afe-1d28-4652-80b9-4ad123b415a4"

        "name": "Documents",

        "id": "Documents",

        "type": "DocFolder",

      },

      {

        "uuid": "7a5374ee-eb7a-4731-997d-5f52f00ebc2e"

        "name": "Requirements",

        "id": "Requirements",

        "type": "Requirement",

        "haveChildren":"true",

        "children": [

          {

            "uuid": "8ccd86e3-5689-43aa-9241-04728447e8f7",

            "name": "001",

            "id": "001",

            "type": "Requirement",

            "children": [],

          }

        ]

      },

      {

        "uuid": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85",

        "name": "Reports",

        "id": "Reports",

        "type": "ReportFolder"

      }

    ],

  }

}

</code></pre>

по умолчанию выдает все дерево с базовым набором из нескольких полей - уникального id uuid, идентефикатора id, являющегося фактически именем json представления на диске, отображаемого имени name, типа type и массива потомков children. 

поле haveChildren присутствует если у узла есть потомки и работает даже когда children не видны в режиме expandable для 2 уровня вложенности

при режиме [expandable] потомки выдаются до 1 уровня вложенности

В случае отсутствия проекта выдаст ошибку E1.

3. Получение данных по поддереву

Method:

GET

Path:

http://localhost:9988/projects/{TEST}/hierarchy/ff42a6f4-f9ac-48c3-b41c-c36395df8a85[/expandable]

{TEST} - имя проекта

id после /hierarchy это id узла для которого получается поддерево, режим /expandable работает аналогично проекту

Без дополнительных параметров

Пример выдачи

<pre><code class="javascript">

{

  "success": true, 

  "result": 

  {

    "uuid": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85",

    "name": "Reports",

    "id": "Reports",

    "type": "ReportFolder",

    "parent": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85"

  }

}

</code></pre>

Содержимое result аналогично описанию одного узла и всех его потомков[или потомков 1 уровня вложенности для expandable] в выдаче проекта

В случае отсутствия проекта выдаст ошибку E1.

В случае отсутствия узла для которого выдается поддерева возвращает ошибку E2.

4. Получение свойств узлов (updated 1.4)

Method:

POST

Path:

http://localhost:9988/projects/TEST/getattributes/

В теле запроса передаются все uuid ы узлов для которых нужно выдать свойства. Конкретная реализация пока уточняется, текущее предположение - просто передавать в текстовом виде с разделителем ;. Возможно будут передаваться в качестве массива по аналогии с передачей данных форм. Пример "4db0fbf4-f383-4740-9d72-891ef112f742;ff42a6f4-f9ac-48c3-b41c-c36395df8a85".

Пример выдачи

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "attributes": {

      "4db0fbf4-f383-4740-9d72-891ef112f742":{

        "Вид": {

          "value": "",

          "rawValue": "",

          "type": "STRING"

        },

        "_index": {

          "value": "1",

          "rawValue": "1",

          "type": "STRING"

        },

        "_name": {

          "value": "Хронология",

          "rawValue": "Хронология",

          "type": "STRING"

        },

        "_type": {

          "value": "Requirement",

          "rawValue": "Requirement",

          "type": "STRING"

        },

        "_id": {

          "value": "001",

          "rawValue": "001",

          "type": "STRING"

        },

        "ForeignID": {

          "value": "1",

          "rawValue": "1",

          "type": "STRING"

        }

      },

      "9dffaddf-a55a-4fa1-a3bc-4a5fade4169f":{

        "Вид": {

          "value": "Заголовок",

          "enumName": "Вид",

          "valueType": "STRING",

          "rawValue": "Заголовок",

          "type": "ENUM"

        },

        "_index": {

          "value": "1",

          "rawValue": "1",

          "type": "STRING"

        },

        "_tags": {

          "value": [

            {

              "value": "section_Архитектура_ПО_Поток_управления",

              "rawValue": "section_Архитектура_ПО"

            }

          ],

          "valuesType": "STRING",

          "type": "LIST"

        },

        "_type": {

          "value": "Requirement",

          "rawValue": "Requirement",

          "type": "STRING"

        },

        "_id": {

          "value": "Поток управления",

          "rawValue": "Поток управления",

          "type": "STRING"

        },

        "_description": {

          "value": " ",

          "rawValue": " ",

          "type": "HTML"

        },

        "exampleNotLocal": {

          "value": " ",

          "rawValue": " ",

          "scope": "SUBTREE",

          "origin": "0b4f4643-fab6-48c6-b694-b8256fc79e0a",

          "type": "HTML"

        },

        "exampleLocal": {

          "value": " ",

          "rawValue": " ",

          "scope": "SUBTREE",

          "type": "HTML"

        },

        "exampleLocal2": {

          "value": " ",

          "rawValue": " ",

          "scope": "DIRECT_CHILDREN",

          "type": "HTML"

        },

        "ForeignID": {

          "value": "2",

          "rawValue": "2",

          "type": "STRING"

        }

      }

    }

  }

}

</code></pre>

В примере выдача свойств двух узлов. Они расположены в result в виде словаря где ключ это id а значение - набор свойств узла.

Свойства включают rawValue - базовое значение свойство которое непосредственно редактируется в инструменте и value - результат подстановки выражений вида {val} позволяющих использовать значения других переменных в текущей.

Также может встречаться "scope" указывающий на область доступности текущего свойства. Большая часть свойств имеют scope равный LOCAL и их значения доступны только на текущем узле. При видимости DIRECT_CHILDREN свойство также доступно в потомках узла в котором оно было определено, а SUBTREE позволяет обеспечить доступность свойства во всем поддереве потомков.

Также стоит отметить origin указывающий на место определения свойства в ситуации когда оно было определено в другом узле. То есть, если в узле присутствует scope и origin одновременно - это означает что это свойство было определено в другом узле. Если есть только scope - это свойство определено в текущем узле но доступно и в его потомках.

5. Метод для работы с ресурсами. Текущая реализация

Method:

GET

Path:

http://localhost:9988/projects/{TEST}/nodes/{n}/resources/{resFolder}/{res}

{Test} имя проекта

{n} - uuid узла

{resFolder} папка с ресурсами(внутри {node_id}_resources, например "images")

{res} имя файла

Возвращает ответ типа APPLICATION_OCTET_STREAM включающий в себя содержимое нужного ресурса. В теле также передается имя файла.

Если ресурса нет то выдается ответ NOT_FOUND типа plain text

Если передано некорректное имя папки с ресурсами(включающее недопустимые символы) то выдается ответ INVALID FOLDER типа plain text

Предположительно появится метод получения ресурсов по списку для множества узлов но потом

Возможный формат передачи данных - json пары

<pre><code class="javascript">

{"uuid":"resfolder/resname","uuid2":"resfolder2/resname2"}

</code></pre>

Возможный тип возвращаемого значения - multipart/mixed. Но при этом размер возвращаемых данных может оказаться значительным

6. Метод для получения связей

Method:

POST

Path:

http://localhost:9988/projects/{TEST}/getlinks

В теле запроса передаются все uuid ы узлов для которых нужно выдать свойства. Текущее предположение - в текстовом виде с разделителем ';'. Пример "4db0fbf4-f383-4740-9d72-891ef112f742;ff42a6f4-f9ac-48c3-b41c-c36395df8a85".

Результат включает в себя аналог словаря uuid:{ссылки}. Если для узла ссылок нет то в выдачу он не попадает.

ссылки разбиты на 4 раздела

linkToRelations - исходящие ссылки по свойствам

linkedByRelations - входящие ссылки по свойствам

linkToTerms - связи от использования термина из другого узла к определению в данном узле

linkedByTerms - связи от использования термина из данного узла к определению в другом узле

Пример выдачи

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "links": {

      "7a5374ee-eb7a-4731-997d-5f52f00ebc2e": {

        "linkToRelations": {

          "reg": [

            {

              "haveChildren": true,

              "name": "Архитектура ПО",

              "id": "Архитектура ПО",

              "type": "Requirement",

              "parent": "7a5374ee-eb7a-4731-997d-5f52f00ebc2e",

              "externalId": "9",

              "uuid": "188f8992-12e1-4acc-bf5a-fd568b1a2161"

            }

          ],

        },

        "linkedByRelations": {

          "d": [

            {

              "haveChildren": true,

              "name": "если E = 2 k -1",

              "id": "if01",

              "type": "Requirement",

              "project": "SQRT",

              "parent": "ba51211b-d1c6-46ae-9333-bdad409b1fdb",

              "uuid": "127bfded-ae30-4365-9274-c116201a4ac1"

            },

            {

              "name": "001",

              "id": "001",

              "type": "Requirement",

              "project": "SQRT",

              "parent": "ebc37a22-15c5-482d-9e4c-8c23461fca39",

              "uuid": "57b80f94-9011-43d8-844f-5bef23e37afb"

            },

            {

              "name": "002",

              "id": "002",

              "type": "Requirement",

              "project": "SQRT",

              "parent": "4b40ef1a-de18-4d71-8825-2ef16b502cd0",

              "uuid": "658b8768-55b8-45b5-99b3-f03ba252acb7"

            }

          ]

        }

      }

    }

  }

} 

</code></pre>

6.5. Получение единичного ресурса

Method:

GET

Paths:

http://localhost:9988/projects/someproject/resources/ed612ae4-ced3-408c-8d64-66d87981611f/subpath.xhtml

или

http://localhost:9988/projects/someproject/resources/ed612ae4-ced3-408c-8d64-66d87981611f/images/1.jpg

Содержат имя проекта {someproject}, uuid узла {ed612ae4-ced3-408c-8d64-66d87981611f} и путь к ресурсу относительно папки {nodeId}_resources.

Стоит отметить что если в описании присутствует конструкция вида {node.resURL}/{img}[пример src="{node.resURL}/RTOS_cf.png"] то для _description путь к картинке фактически будет составлять {nodeId}_resources/_description/{img}[src="...RTOS_CONTROL_FLOW_resources\_description\RTOS_cf.png"]

7. Установка свойств (updated 1.4)

Method:

PUT

Datatype:

multipart/form-data или application/json

Path:

http://localhost:9988/projects/{TEST}/nodes/{uuid_of_node}/attributes/

В теле запроса передаются значения свойств которые требуется изменить. Пример запроса ниже. Значение свойств которые не переданы в запросе остаются неизмеными. Сами свойства передаются через application/json поле "input". Изображения передаются в виде прикрепленных файлов в поле images.//TODO добавить пример.

При использовании типа application/json вместо multipart/form-data свойства передаются непосредственно в теле запроса

Стоит отметить, что устанавливается значение соответсвующее выдаче rawValue, то есть с использованием конструкций вида {val}. Если установить значения после подстановки, то в результате эти данные будут утеряны

<pre><code class="javascript">

{

  "attributes":

    {

      "test":

        {

          "value":"2"

        },

      "test2":

        {

          "value":"3", "type": "INT"

        }

    }

}

</code></pre>

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

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "attributes": {

      "test2": {

        "value": "3",

        "type": "INT"

      },

      "_index": {

        "value": "8",

        "type": "STRING"

      },

      "test": {

        "value": "2",

        "type": "STRING"

      },

      "_tags": {

        "valuesType": "STRING",

        "value": [

          {

            "value": "section_Архитектура_ПО"

          }

        ],

        "type": "LIST"

      },

      "_type": {

        "value": "Requirement",

        "type": "STRING"

      },

      "_id": {

        "value": "Архитектура ПО",

        "type": "STRING"

      }

    }

  }

}

</code></pre>

7b. Пример установки картинки

Запрос

http://127.0.0.1:9988/projects/TEST/nodes/4db0fbf4-f383-4740-9d72-891ef112f742/attributes

Метод

PUT

Тип значения

multipart/form-data

Два поля в содержимом

text part с именем input, тип application/json

{   "attributes":     {       "_description":         {         "type":"HTML",  "value":"2<img src='example.png'/>"          }     } }

file part с именем images, загружена картинка example.png

если нужно больше изображений то следует добавить еще полей с именем images.

8. Замена свойств

Аналогичен 7, отличается использованием метода POST. Удаляет все свойства которые не перечисленны в запросе

9. Удаление свойств

Method:

DELETE

Path:

http://localhost:9988/projects/{TEST}/nodes/{n}/attributes/

{TEST} - имя проекта

{n} - uuid узла

В теле запроса передаются все имена свойств которые требуется удалить в текстовом виде с разделителем ';'. Пример

_name;attributeName

Результат включают в себя список оставшихся свойств. 

Пример выдачи

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "attributes": [

      "Вид",

      "Производное",

      "_index",

      "_tags",

      "_type",

      "_id",

      "ForeignID"

    ],

  }

}

</code></pre>

10. Создание проекта

Method:

PUT

Path:

http://localhost:9988/projects/{new_name}

{new_name} - имя проекта

Возвращает 

<pre><code class="javascript">

{

  "success": true,

  "result": {}

}

</code></pre>

либо если проект уже существует 

<pre><code class="javascript">

{

  "success": false,

  "error": {

    "code": "project_exists",

    "message": "Specified project already exists",

    "extra": {}

  }

}

</code></pre>

10. Удаление проекта

Method:

DELETE

Path:

http://localhost:9988/projects/{name}

{name} - имя проекта

Возвращает 

<pre><code class="javascript">

{

  "success": true,

  "result": {}

}

</code></pre>

либо если проект не найден

<pre><code class="javascript">

{

  "success": false,

  "error": {

    "code": "project_not_found",

    "message": "Specified project does not exists",

    "extra": {}

  }

}

</code></pre>

11. Создание узла

Method:

PUT

Path:

http://localhost:9988/projects/{project_name}/create

project_name - имя проекта

Datatype:

multipart/form-data или application/json

Для multipart/form-data в теле содержится два поля - input содержит json с описанием узла, images содержит изображения.

Для application/json в теле содержится только json с описанием

<pre><code class="javascript">

{

  "parent": "516bbbbc-babf-45d6-a146-61db334411be",

  "type":"Requirement",

  "id":"002",

  "attributes":{

    "test": {

      "value": "13d23",

      "type": "INT"

    },

    "_name": {

      "value": "{test} test 123"

    },

    "Ref": {

      "type": "REFERENCE",

      "value":"test"

    },

    "_description": {

      "value":"test desc <img src='strange.png' alt='strange.xcf'/>", "type":"HTML"

    }

  }

}

</code>

</pre>

id является опциональным, если его не указывать он будет формироваться автоматически

Пример возвращаемого значения

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "name": "13d23 test 123",

    "id": "002",

    "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3",

    "parent": "1f6e9e4f-4f63-446b-bddd-15838c15c212",

    "attributes": {

      "Ref": {

        "value": "*Missing(Ref): 'test'",

        "type": "REFERENCE"

      },

      "test": {

        "value": "13d23",

        "type": "INT"

      },

      "_name": {

        "value": "13d23 test 123",

        "type": "STRING"

      },

      "_type": {

        "value": "Requirement",

        "type": "STRING"

      },

      "_id": {

        "value": "002",

        "type": "STRING"

      },

      "_description": {

        "value": "test desc <img src='strange.png' alt='strange.xcf'/>",

        "type": "HTML"

      }

    }

  }

}

</code>

</pre>

12. Удаление узла

Method:

DELETE

Path:

http://localhost:9988/projects/{project_name}/node

project_name - имя проекта

В теле в виде текста содержится идентефикатор узла, например UUID, но можно использовать и другие способы идентефикации

Пример

<pre><code class="javascript">

03745ff6-6f9f-4517-b011-c92ca6081a47

</code>

</pre>

Пример удачного удаления. Возвращается иерархия на уровне родителя удаленного узла

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "haveChildren": true,

    "name": "Requirements",

    "id": "Requirements",

    "type": "Requirement",

    "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212",

    "children": [

      {

        "name": "002",

        "id": "002",

        "type": "Requirement",

        "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3"

      },

      {

        "name": "004",

        "id": "004",

        "type": "Requirement",

        "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18"

      },

      {

        "name": "005",

        "id": "005",

        "type": "Requirement",

        "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318"

      },

      {

       "name": "006",

       "id": "006",

       "type": "Requirement",

       "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2"

      },

      {

        "name": "007",

        "id": "007",

        "type": "Requirement",

        "uuid": "40155667-942e-43a6-9861-3c5b05adccfb"

      },

    ],

  }

}

</code>

</pre>

Пример с отсутствующим узлом

<pre><code class="javascript">

{

  "success": false,

  "error": {

    "code": "qid_not_found",

    "message": "Specified QID does not exists",

    "extra": {}

  }

}

</code>

</pre>

13. Перемещение узла

Method:

POST

Path:

http://localhost:9988/projects/{project_name}/nodes/{uuid}/move

project_name - имя проекта

uuid - идентефикатор узла который требуется переместить

В теле содержится json с описанием параметров переноса

Пример

<pre><code class="javascript">

{

  "parent":"2ce727b8-0740-4344-988f-3155d7cea5f2",

  "node":"90ae2683-d4c7-4a97-ae03-255f449f9318",

  "position":"1"

}

</code>

</pre>

parent - указание на нового родителя

node и position - опциональные поля для того чтобы переместить узел в определенное место, могут не включаться в запрос

node при указании задает узел относительно которого нужно определить новую позицию

position может принимать значение <0 или >=1. Если он <0 то узел будет перемещен на позицию до целевого узла, если >=0 то после.

Пример удачного удаления. Возвращается иерархия на уровне нового родителя узла

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "haveChildren": true,

    "name": "Requirements",

    "id": "Requirements",

    "type": "Requirement",

    "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212",

    "children": [

      {

        "name": "002",

        "id": "002",

        "type": "Requirement",

        "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3"

      },

      {

        "name": "004",

        "id": "004",

        "type": "Requirement",

        "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18"

      },

      {

        "name": "005",

        "id": "005",

        "type": "Requirement",

        "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318"

      },

      {

       "name": "006",

       "id": "006",

       "type": "Requirement",

       "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2"

      },

      {

        "name": "007",

        "id": "007",

        "type": "Requirement",

        "uuid": "40155667-942e-43a6-9861-3c5b05adccfb"

      },

    ],

  }

}

</code>

</pre>

14. Начало транзакции

Method:

POST

Path:

http://localhost:9988/projects/{project_name}/startTransaction

Тело содержить имя транзакиции в виде plaint текста, обычно включает имя проекта

project_name - имя проекта

Начинает транзакцию с набором действий которые впоследствии можно отменить

15. Коммит транзакции

Method:

POST

Path:

http://localhost:9988/projects/{project_name}/commitTransaction

project_name - имя проекта

Применяет транзакцию

16. Откат транзакции

Method:

POST

Path:

http://localhost:9988/projects/{project_name}/rollbackTransaction

project_name - имя проекта

Отменяет действие транзакции и возвращает все в состояние до начала транзакции

17. Отмена прошлой транзакции

Method:

GET

Path:

http://localhost:9988/projects/undo

Отменяет предидущую транзакцию.

18. Возврат отмененной транзакции

Method:

GET

Path:

http://localhost:9988/projects/redo

Возвращает отмененную транзакцию.

19. Список действий к отмене

Method:

GET

Path:

http://localhost:9988/projects/undoactions

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

Пример ответа

<pre><code class="javascript">

{

  "success" : true,

  "result" : {

    "transactions" : [ "Move Element", "Move Element" ]

  }

}

</code>

</pre>

20. Список действий к возвращению

Method:

GET

Path:

http://localhost:9988/projects/redoactions

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

Пример ответа

<pre><code class="javascript">

{

  "success" : true,

  "result" : {

    "transactions" : [ "Move Element", "Move Element" ]

  }

}

</code>

</pre>

21. Получение связей для узлов

Method:

POST

Path:

http://localhost:9988/projects/{project_name}/getlinks

project_name - имя проекта

В теле запроса список идентификаторов узлов для которых требуется получить связи разделенный ;(например uuid ов)

Возвращает список связей и узлов если связи удачно разрешились. Пример возвращаемого значения для узла 99bf5072-822a-41a8-bb54-eb4755773e84.

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "links": {

      "99bf5072-822a-41a8-bb54-eb4755773e84": {

        "linkedByTerms": {

          "uintptr_t": [

            {

              "name": "JetConfigTreeGet_UINTPTR",

              "id": "001",

              "type": "TextNode",

              "parent": "c4ffcef4-2926-4c50-9d63-b5fe5ecf142f",

              "externalId": "3326",

              "uuid": "cda13be2-e8f5-4f28-9662-d4a83d2280d2"

            }

          ],

        },

        "linkedByRelations": {

          "term-uintptr_t": [

            {

              "name": "JetConfigTreeGet_UINTPTR",

              "id": "005",

              "type": "TextNode",

              "parent": "c4ffcef4-2926-4c50-9d63-b5fe5ecf142f",

              "externalId": "3326",

              "uuid": "cda13be2-e8f5-4f28-9662-d4a83d2280d2"

            }

          ],

        }

      }

    }

  }

}

</code>

</pre>

Возвращаемое значение представляет собой объект links в котором расположен словарь uuid->связи. Информация о связях заключена в 4 подгруппах. Префикс linkTo обозначают исходящие ссылки, linkedBy входящие

linkToTerms

linkedByTerms

linkToRelations

linkedByRelations

Суффиксы обозначают вид связи - связь по свойствам Relations и связь по определению и использованию терминов Terms.

Подробнее про термины можно прочитать в доках http://requality.org/ru/glossary.ru.html#glossary_term

22. Получить список определений перечисляемцых типов

Method:

GET

Path:

http://localhost:9988/projects/{project_name}/enumDefinitions

project_name - имя проекта

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

enumDefinitions:{словарь имя_перечисления->опредление}

где определение это {valuesType:тив,value:[значения]}

значения - набор пар {value:значение, comment:комментарий}

значение имеет тип определенный в valuesType. На данный момент поддерживаются только перечислимые типы со строками

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

Пример выдачи значений

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "enumDefinitions": {

      "Test": {

        "valuesType": "STRING",

        "values": [

          {

            "value": "val01",

            "comment": null

          },

          {

            "value": "val02",

            "comment": null

          }

        ]

      },

      "Test2": {

        "valuesType": "STRING",

        "values": [

          {

            "value": "val",

            "comment": null

          }

        ]

      }

    }

  }

}

</code>

</pre>

23. Поиск узлов по строке

Method:

POST

Path:

http://localhost:9988/projects/{project_name}/search

project_name - имя проекта

В теле запроса передается следующее.

<pre><code class="javascript">

{

	"request":"A",

	"attributes":[],

        "caseSensitive":"false",

	"rootNode":"/Requirements"

}

</code>

</pre>

request - сам запрос, в attributes передается список имен свойств, в rootNode - корень поиска,

caseSensitive - запрос на строгий поиск по регистру при true

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

Пример выдачи значений

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "nodes": [

      {

        "name": "test",

        "uuid": "c4ffcef4-2926-4c50-9d63-b5fe5ecf142f",

        "sequentialId": "11040"

      },

      {

        "name": "test2",

        "uuid": "cda13be2-e8f5-4f28-9662-d4a83d2280d2",

        "sequentialId": "11041"

      }

    }

  }

}

</code>

</pre>

Отчеты.

 Получение настроек генерации отчетов

В рамках работы инструмента возможно генерировать отчеты по одному из доступных шаблонов.

Для этого сначала создается объект с настройками генерации а затем по нему становится возможным генерировать экземпляры отчетов

Для настроек генерации можно задавать свойсва также как с другими узлами

24. Вызов генерации отчета (!внимание - генерируется только 1 отчет за раз)

Method:

POST

Path:

http://localhost:9988/projects/{project}/reportSettings/{r}/generate

{r}-uuid настроек генерации

Возвращает ссылку на новый экземпляр отчета по шаблону, процесс генерации запускается

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "id": {

      "qid": "/Reports/001(2021-10-13_22-41-23)",

      "uuid": "aab07d4f-a79a-45f8-ba95-32cddc6b58f8",

      "uv": "Reports/001(2021-10-13_22-41-23)"

    },

    "href": null

  }

}

</code></pre>

25. Проверка статуса генерации отчета

Method:

POST

Path:

http://localhost:9988/projects/{project}/reports/{r}/generationStatus

Возвращает состояние генерации отчета

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "percentage": 0,

    "task": "init main generation - arch"

  }

}

</code></pre>

task имя выполняемой задачи

percentage - примерный общий процент

Если генерация отчета завершена в task записывается "generation over"

26. Получение полного содержимого отчета в виде zip архива(после генерации)

Method:

GET

Path:

http://localhost:9988/projects/{project}/reports/{r}/export

Возвращает multipart/mixed

В теле записана длина архива и зип архив с содержимым отчета

27. Просмотр содержимого отчета без ресурсов(после генерации)

Method:

GET

Path:

http://localhost:9988/projects/{project}/reports/{r}

Возвращает html

28. Получение списка шаблонов отчетов и их групп

Method:

GET

Path:

http://localhost:9988/projects/{project}/reportSettings/templates

Возвращает в формате

<pre><code class="javascript">

{

  "success": true,

  "result": [

    {

      "id": "typical",

      "type": "group",

      "name": "Отчёты для решения типовых задач",

      "description": "Отчеты для решения типовых задач.",

      "children": [

        {

          "id": "typical:com.unitesk.requality.reports.tableview",

          "type": "template",

          "name": "Чтение требований",

          "description": "",

          "children": null

        },...

      ]

    },...

  ]

}

</code></pre>

id - id группы шаблонов или шаблона, id шаблона включает id группы

type: template или group, шаблон или группа

name - отображаемое имя группы или шаблона

description - описание группы или шаблона

children - список потомков

29. Получение информации по используемым в определенном шаблоне параметам

Method:

GET

Path:

http://localhost:9988/projects/{project}/reportSettings/templates/{templateId}

Возвращает информацию об определенном шаблоне и используемых в нем параметрах. Пример для шаблона com.unitesk.requality.reports.revision

<pre><code class="javascript">

{

  "success" : true,

  "result" : [ {

    "name" : "simplifiedAttrs",

    "description" : "Use siplified notation for attribtues",

    "type" : "BOOL",

    "defValue" : "true",

    "paramDataSource" : null,

    "attributes" : null

  }, {

    "name" : "isHTML",

    "description" : "If true display html instead of raw markup",

    "type" : "BOOL",

    "defValue" : "true",

    "paramDataSource" : null,

    "attributes" : null

  }, {

    "name" : "sideBySide",

    "description" : "If true enables special mode for comparation - shows version before and after near side by site in a single row.",

    "type" : "BOOL",

    "defValue" : "false",

    "paramDataSource" : null,

    "attributes" : null

  }, {

    "name" : "revisonPrev",

    "description" : "Previous revision for comparation. Needs to be more recent than revisionCur. Also may be HEAD or '' for workspace.",

    "type" : "REVISION,STRING",

    "defValue" : "HEAD",

    "paramDataSource" : "_repoTreePagedVersion",

    "attributes" : null

  }, {

    "name" : "revisonCur",

    "description" : "Next revision for comparation. Empty value is workspace version. Needs to be older than revisionPrev. Also may be HEAD or '' for workspace.",

    "type" : "REVISION,STRING",

    "defValue" : "",

    "paramDataSource" : "_repoTreePagedVersion",

    "attributes" : null

  } ]

}

</code></pre>

result содержит информацию по используемым в шаблоне параметрам. name - имя параметра, description - описание параметра, type - описание типов с разделителем в виде ",". Последний из типов всегда является одним из стандартных типов AttributeType(STRING, LIST и т.д.). При этом LIST использует нотацию LIST[TYPE], например LIST[STRING] или LIST[LIST[STRING]]. Для не стадартных типов могут быть созданы отдельные редакторы и обработчики. Для REVISION, например, предпологается использование источника данных _repoTreePagedVersion и представляет собой выбор ревизии из списка доступных.

defValue - значение по умолчанию, имеет стандартный тип из type(самый правый)

paramDataSource - источник данных для параметра, можно получить данные по запросу

attributes - описание атрибутов в виде которых хранится параметр. При этом по умочанию параметр хранится как атрибут с именем, типом и значением аналогичным параметру

30.

Method:

POST

Path:

http://localhost:9988/projects/{project}/nodes/{node}/dataSources/{dataSourceId}

dataSourceId - id источника данных, например _repoTreePagedVersion

node - uuid определенного узла, например, настроек генерации отчета

project - имя проекта

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

Например, для _repoTreePagedVersion

<pre><code class="javascript">

{

  "success": true,

  "result": {

    "values": {

      "value": [

        {

          "value": {

            "branch": {

              "value": "refs/heads/master"

            },

            "parents": {

              "value": "069d87f22753296191fa44821a26e6d0a33e7a88"

            }

          },

          "valuesType": "STRING"

        },

        {

          "value": {

            "author": {

              "value": "name [email]"

            },

            "branch": {

              "value": "refs/heads/master"

            },

            "date": {

              "value": "2022-01-16 01:59:06"

            },

            "fullMessage": {

              "value": "[#2209][#101]Descr.\n\n"

            },

            "parents": {

              "value": "8b9f27d089faa5afefdb1dff21f14d1d43746a19"

            },

            "revision": {

              "value": "069d87f22753296191fa44821a26e6d0a33e7a88"

            },

            "shortMessage": {

              "value": "[#2209][#101] Short message..."

            }

          },

          "valuesType": "STRING"

        },...

      ],

      "valuesType": "MAP"

    }

  }

}

</code></pre>

values содержит описание значений по источнику данных, в примере они имеют тип MAP со значениями типа STRING

поддерживается также режим постраничной выдачи

http://localhost:9988/projects/{project}/nodes/{node}/dataSources/{dataSourceId}/page10_0

в нотации page10_0 10 - количество записей на странице, 0 - номер старницы

31.

Method:

GET

Path:

http://localhost:9988/resources/getApplicationSession

Возвращает строку, идентефикатор сессии сервера

32.

Method:

GET

Path:

http://localhost:9988/resources/listWebSocketProviders

Возвращает json объект с состоянием веб сокетов для разных применений. Пример выдачи ниже     

{

  "success": true,

  "result": "[{\"port\":\"9920\",\"name\":\"markup\",\"status\":\"STARTED\"},{\"port\":\"9922\",\"name\":\"reportView\",\"status\":\"STARTED\"},{\"port\":\"9924\",\"name\":\"review\",\"status\":\"STARTED\"},{\"port\":\"9923\",\"name\":\"moduleeditor\",\"status\":\"STARTED\"},{\"port\":\"9921\",\"name\":\"unieditor\",\"status\":\"STARTED\"}]"

}

port - занятый порт, name - имя, статус - состояние связанного объекта

33.

Method:

GET

Path:

http://localhost:9988/resources/getResourcesProviderStatus

Возвращает json описывающий состояние сервера ресурсов от которого можно получить содержимое документов, отчетов, редактора требований, связанные ресурсы

Пример выдачи

{

  "success": true,

  "result": "{\"port\":\"9807\",\"status\":\"STARTED\"}"

}

34.

Method:

GET

Path:

http://localhost:9988/resources/startSession/{project}:{doc}:{port}

Начинает новую сессию взаимодействия с одним из серверов веб сокетов. project - имя проекта, doc - UUID документа, port - номер порта сервера 

Возвращает строку - номер сессии 

35.

Method:

GET

Path:

http://localhost:9988/resources/stopSession/{session}

Используется чтобы закрыть открытую на 34. сессию и освободить ресурсы

36.

Method:

GET

Path:

http://localhost:9988/projects/{project}/descendantsUUIDs/

Возвращает список всех потомков узла /Requirements

Пример выдачи

{

  "success" : true,

  "result" : {

    "nodes" : [ UUID1, ... ]

}

37.

Method:

GET

Path:

http://localhost:9988/projects/{project}/descendantsUUIDs/{node}

Возвращает список всех потомков узла с UUID node

Пример выдачи

{

  "success" : true,

  "result" : {

    "nodes" : [ UUID1, ... ]

}

38.

Method:

GET

Path: /projects/{project}/nodes/{uuid}/source

Возвращает представление соответствующего узла на диске в формате json.

Предпологается использование в справочных целях или для отладки. Для получения данных и последующего редактирования узлов следует использовать соотвествующие средства API

39.

Method: POST

Path: /projects/{project}/nextNodeId/

В теле запроса передаются:

{"parent":~parent~, "type":~type~}

parent - uuid узла, в котором требуется узнать следующий id для нового узла (обязательный параметр)

type - тип создаваемого узла (необязательный)

Возвращается следующий id для создаваемого потомка нужного типа (или, если тип явно не указан, типа узла родителя)

E1. 

Ошибка - проект не найден

<pre><code class="javascript">

{

  "success": false,

  "error": {

    "code": "project_not_found",

    "message": "Specified project does not exists",

    "extra": {}

  }

}

</code>

</pre>

E2. 

Ошибка - узел не найден

<pre><code class="javascript">

{

  "success": false,

  "error": {

    "code": "node_not_found",

    "message": "Specified node does not exists",

    "extra": {}

  }

}

</code>

</pre>