Project

General

Profile

Actions
History

Design » API »

APIForNG

По текущей модели предполагается использование следующих методов:
Для всех методов по умолчанию используется один заголовочный параметр
Authorization со значением Bearer 36AC0A0F7F271314B72986EB54DB2343

1.Получение списка проектов (updated 1.4)
Method:
GET
Path:
http://localhost:9988/projects
Без дополнительных параметров.
Возвращает пары "имя хранимое: имя представления"
Пример "some-local-project:project". При этом первое используется для обращения к определенному проекту, в том числе при помощи API вызовов, а второе - для ссылок на артефакты проекта в других проектах. Например, так можно представить другой проек в котором будет ссылка вида project::Requirements.
Пример выдачи

{
  "success" : true,
  "result" : {
    "projects" : [ "Example":"Example", "з1":"з1", "someos-arch":"arch", "somestpo":"stpo"],
    "count" : 4
  }
}

2. Получение содержимого проекта(иерархия), для expandable - ограниченное 1м уровнем
Method:
GET
Path:
http://localhost:9988/projects/{arch}[/expandable]
Здесь {arch} - имя проекта, на данный момент регистрозависимо
Без дополнительных параметров
Пример выдачи

{
  "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" 
      }
    ],
  }
}

по умолчанию выдает все дерево с базовым набором из нескольких полей - уникального 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 работает аналогично проекту
Без дополнительных параметров
Пример выдачи

{
  "success": true, 
  "result": 
  {
    "uuid": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85",
    "name": "Reports",
    "id": "Reports",
    "type": "ReportFolder",
    "parent": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85" 
  }
}

Содержимое 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".
Пример выдачи

{
  "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" 
        }
      }
    }
  }
}

В примере выдача свойств двух узлов. Они расположены в result в виде словаря где ключ это id а значение - набор свойств узла.
Свойства включают rawValue - базовое значение свойство которое непосредственно редактируется в инструменте и value - результат подстановки выражений вида {val} позволяющих использовать значения других переменных в текущей.
Также может встречаться "scope" указывающий на область доступности текущего свойства. Большая часть свойств имеют scope равный LOCAL и их значения доступны только на текущем узле. При видимости DIRECT_CHILDREN свойство также доступно в потомках узла в котором оно было определено, а SUBTREE позволяет обеспечить доступность свойства во всем поддереве потомков.
Также стоит отметить origin указывающий на место определения свойства в ситуации когда оно было определено в другом узле. То есть, если в узле присутствует scope и origin одновременно - это означает что это свойство было определено в другом узле. Если есть только scope - это свойство определено в текущем узле но доступно и в его потомках.

4.5. Получение набора свойств для узлов по выбранному набору ключей
Method:
POST
Path:
http://localhost:9988/projects/TEST/getspecattributes/
В теле запроса передается json содержащий dictionary в котором в качестве ключей участвуют uuid ы узлов для которых нужно выдать свойства а в качестве значений - массив строк с ключами. Для выдачи значений аналогично 4. нужно добавить специальный ключ "[visible]" при использовании которого к выдаче будут добавлены видимые свойства. Пример запроса -


{
    "uuid_1": [
        "attr_name_1",
        "attr_name_2" 
    ],
    "uuid2": [
        "attr_name_3",
        "attr_name_2" 
    ]
}

Пример выдачи
{
  "success": true,
  "result": {
    "attributes": {
      "uuid_1":{
        "attr_name_1": {
          "value": "attributes value",
          "rawValue": "attributes value",
          "type": "STRING" 
        },
        "attr_name_2": {
          "value": "1",
          "rawValue": "1",
          "type": "STRING" 
        }
      },
      "uuid_2":{
        "attr_name_3": {
          "value": "Заголовок",
          "enumName": "Вид",
          "valueType": "STRING",
          "rawValue": "Заголовок",
          "type": "ENUM" 
        },
        "attr_name_2": {
          "value": "2",
          "rawValue": "2",
          "type": "STRING" 
        }
      }
    }
  }
}

В примере выдача свойств двух узлов. Они расположены в 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 пары

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

Возможный тип возвращаемого значения - 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 - связи от использования термина из данного узла к определению в другом узле
Пример выдачи

{
  "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" 
            }
          ]
        }
      }
    }
  }
}

6.5. Получение единичного ресурса
Method:
GET
Paths:
http://localhost:9988/projects/someproject/nodes/resources/ed612ae4-ced3-408c-8d64-66d87981611f/subpath.xhtml
или
http://localhost:9988/projects/someproject/nodes/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"]

6.6. Получение списка ресурсов для узла
Method:
GET
Path:
http://localhost:9988/projects/someproject/nodes/ed612ae4-ced3-408c-8d64-66d87981611f/resources
Возвращает полный список ресурсов связанных с узлом с указанием на подпапки в которых они лежат
Пример {
"success": true,
"result": {
"resources": {
"_description":{
"325472601571f31e1bf00674c368d335.png":{
"mime": "image/png",
"filename": "325472601571f31e1bf00674c368d335.png"
}
}
}
}
}

6.7. Удаление отдельного ресурса
Method:
DELETE
Path:
http://localhost:9988/projects/someproject/nodes/ed612ae4-ced3-408c-8d64-66d87981611f/resources/{resFolder}/{resName}
или
http://localhost:9988/projects/someproject/nodes/ed612ae4-ced3-408c-8d64-66d87981611f/resources/{resName}
Удаляет ресурс и возвращает ответ 200 если удаление завершено успешно или 404 если ресурс не обнаружен

6.8. Удаление набора ресурсов
Method:
DELETE
Path:
http://localhost:9988/projects/someproject/nodes/ed612ae4-ced3-408c-8d64-66d87981611f/resources/
В теле запроса разделенные ; указаны пути к ресурсам которые требуется удалить. Например, "_description/325472601571f31e1bf00674c368d335.gif;_description/325472601571f31e1bf00674c368d335.png". Допускается оборачивание путей в ' или ". В результате запроса будет произведена попытка удалить указанные ресурсы.
Возвращает списки удаленных и не обнаруженных ресурсов. Пример {
"success": true,
"result": {
"deleted": {
"resources": {
"_description":{
"633d183b020d2072b6b43d0782781032.jpeg":{
"mime": "image/jpeg",
"filename": "633d183b020d2072b6b43d0782781032.jpeg"
}
}
}
},
"notfound": {
"resources": {
"_description":{
"non-exists.png"{
"mime": "image/png",
"filename": "non-exists.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}. Если установить значения после подстановки, то в результате эти данные будут утеряны

{
  "attributes":
    {
      "test":
        {
          "value":"2" 
        },
      "test2":
        {
          "value":"3", "type": "INT" 
        }
    }
}

Возвращает текущий набор видимых распологающихся в узле свойств
{
  "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" 
      }
    }
  }
}

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
Результат включают в себя список оставшихся свойств.
Пример выдачи

{
  "success": true,
  "result": {
    "attributes": [
      "Вид",
      "Производное",
      "_index",
      "_tags",
      "_type",
      "_id",
      "ForeignID" 
    ],
  }
}

10. Создание проекта
Method:
PUT
Path:
http://localhost:9988/projects/{new_name} {new_name} - имя проекта
Возвращает 

{
  "success": true,
  "result": {}
}

либо если проект уже существует 
{
  "success": false,
  "error": {
    "code": "project_exists",
    "message": "Specified project already exists",
    "extra": {}
  }
}

10. Удаление проекта
Method:
DELETE
Path:
http://localhost:9988/projects/{name} {name} - имя проекта
Возвращает 

{
  "success": true,
  "result": {}
}

либо если проект не найден
{
  "success": false,
  "error": {
    "code": "project_not_found",
    "message": "Specified project does not exists",
    "extra": {}
  }
}

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 с описанием

{
  "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" 
    }
  }
}

id является опциональным, если его не указывать он будет формироваться автоматически
Пример возвращаемого значения
{
  "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" 
      }
    }
  }
}

12. Удаление узла
Method:
DELETE
Path:
http://localhost:9988/projects/{project_name}/node
project_name - имя проекта
В теле в виде текста содержится идентефикатор узла, например UUID, но можно использовать и другие способы идентефикации
Пример

03745ff6-6f9f-4517-b011-c92ca6081a47

Пример удачного удаления. Возвращается иерархия на уровне родителя удаленного узла
{
  "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" 
      },
    ],
  }
}

Пример с отсутствующим узлом
{
  "success": false,
  "error": {
    "code": "qid_not_found",
    "message": "Specified QID does not exists",
    "extra": {}
  }
}

13. Перемещение узла
Method:
POST
Path:
http://localhost:9988/projects/{project_name}/nodes/{uuid}/move
project_name - имя проекта
uuid - идентефикатор узла который требуется переместить
В теле содержится json с описанием параметров переноса
Пример

{
  "parent":"2ce727b8-0740-4344-988f-3155d7cea5f2",
  "node":"90ae2683-d4c7-4a97-ae03-255f449f9318",
  "position":"1" 
}

parent - указание на нового родителя
node и position - опциональные поля для того чтобы переместить узел в определенное место, могут не включаться в запрос
node при указании задает узел относительно которого нужно определить новую позицию
position может принимать значение <0 или >=1. Если он <0 то узел будет перемещен на позицию до целевого узла, если >=0 то после.
Пример удачного удаления. Возвращается иерархия на уровне нового родителя узла
{
  "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" 
      },
    ],
  }
}

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
Получение списка действий которые можно отменить.
Пример ответа

{
  "success" : true,
  "result" : {
    "transactions" : [ "Move Element", "Move Element" ]
  }
}

20. Список действий к возвращению
Method:
GET
Path:
http://localhost:9988/projects/redoactions
Получение списка действий которые можно вернуть.
Пример ответа

{
  "success" : true,
  "result" : {
    "transactions" : [ "Move Element", "Move Element" ]
  }
}

21. Получение связей для узлов
Method:
POST
Path:
http://localhost:9988/projects/{project_name}/getlinks
project_name - имя проекта
В теле запроса список идентификаторов узлов для которых требуется получить связи разделенный ;(например uuid ов)
Возвращает список связей и узлов если связи удачно разрешились. Пример возвращаемого значения для узла 99bf5072-822a-41a8-bb54-eb4755773e84.

{
  "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" 
            }
          ],
        }
      }
    }
  }
}

Возвращаемое значение представляет собой объект 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 в выдаче на данный момент)
Пример выдачи значений

{
  "success": true,
  "result": {
    "enumDefinitions": {
      "Test": {
        "valuesType": "STRING",
        "values": [
          {
            "value": "val01",
            "comment": null
          },
          {
            "value": "val02",
            "comment": null
          }
        ]
      },
      "Test2": {
        "valuesType": "STRING",
        "values": [
          {
            "value": "val",
            "comment": null
          }
        ]
      }
    }
  }
}

23. Поиск узлов по строке
Method:
POST
Path:
http://localhost:9988/projects/{project_name}/search
project_name - имя проекта
В теле запроса передается следующее.

{
    "request":"A",
    "attributes":[],
        "caseSensitive":"false",
    "rootNode":"/Requirements" 
}

request - сам запрос, в attributes передается список имен свойств, в rootNode - корень поиска,
caseSensitive - запрос на строгий поиск по регистру при true
Возвращает для выбранного проекта узлы для которых указанная подстрока есть в одном из публичных свойств.
Пример выдачи значений
{
  "success": true,
  "result": {
    "nodes": [
      {
        "name": "test",
        "uuid": "c4ffcef4-2926-4c50-9d63-b5fe5ecf142f",
        "sequentialId": "11040" 
      },
      {
        "name": "test2",
        "uuid": "cda13be2-e8f5-4f28-9662-d4a83d2280d2",
        "sequentialId": "11041" 
      }
    }
  }
}

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

24. Вызов генерации отчета (!внимание - генерируется только 1 отчет за раз)
Method:
POST
Path:
http://localhost:9988/projects/{project}/reportSettings/{r}/generate {r}-uuid настроек генерации
Возвращает ссылку на новый экземпляр отчета по шаблону, процесс генерации запускается

{
  "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
  }
}

24.5 Получение идентефикатора последнего сгенерированного\генерируемого отчета
Method:
GET
Path:
http://localhost:9988/projects/{project}/reportSettings/{r}/lastGeneratedState
Позволяет получить идентефикатор генерируемого(или последнего сгенерированного) отчета если генерация была запущена в пределах текущего запуска сервера.
Если генерация не была запущена возвращает ошибку "Cannot get generation status because it was not started on current application session" 

{
  "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
  }
}

25. Проверка статуса генерации отчета
Method:
POST
Path:
http://localhost:9988/projects/{project}/reports/{r}/generationStatus
Возвращает состояние генерации отчета

{
  "success": true,
  "result": {
    "percentage": 0,
    "task": "init main generation - arch" 
  }
}

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
Возвращает в формате

{
  "success": true,
  "result": [
    {
      "id": "typical",
      "type": "group",
      "name": "Отчёты для решения типовых задач",
      "description": "Отчеты для решения типовых задач.",
      "children": [
        {
          "id": "typical:com.unitesk.requality.reports.tableview",
          "type": "template",
          "name": "Чтение требований",
          "description": "",
          "children": null
        },...
      ]
    },...
  ]
}

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

{
  "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
  } ]
}

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

{
  "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" 
    }
  }
}

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 для создаваемого потомка нужного типа (или, если тип явно не указан, типа узла родителя)

40.
Method: GET
Path: /projects/{project}/nodes/{uuid}/relatedLocations
Возвращает список связанных фрагментов и документов(или требований) при вызове на требовании\текстовом узле(документе) соотвественно
Пример выдачи для документа {
"success": true,
"result": [ {
"uuid": "74a3945c-e412-48f3-9af0-265363d2276e",
"type": "Location",
"uvid": "Documents/article_gerl_kild_khor_fallback.xhtml/74a3945c-e412-48f3-9af0-265363d2276e",
"qid": "/Documents/article_gerl_kild_khor_fallback.xhtml/74a3945c-e412-48f3-9af0-265363d2276e",
"label": "003#1",
"related": [ {
"uuid": "1853a87f-068c-44c3-ab44-60b8dc421d20",
"type": "Requirement",
"uvid": "003",
"qid": "/Requirements/003",
"label": "003"
}
]
}, {
"uuid": "301e164c-59b7-47a0-92e3-e8a9b0ac141a",
"type": "Location",
"uvid": "Documents/article_gerl_kild_khor_fallback.xhtml/301e164c-59b7-47a0-92e3-e8a9b0ac141a",
"qid": "/Documents/article_gerl_kild_khor_fallback.xhtml/301e164c-59b7-47a0-92e3-e8a9b0ac141a",
"label": "003#2",
"related": [ {
"uuid": "1853a87f-068c-44c3-ab44-60b8dc421d20",
"type": "Requirement",
"uvid": "003",
"qid": "/Requirements/003",
"label": "003"
}
]
}
]
}

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

{
  "success": false,
  "error": {
    "code": "project_not_found",
    "message": "Specified project does not exists",
    "extra": {}
  }
}

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

{
  "success": false,
  "error": {
    "code": "node_not_found",
    "message": "Specified node does not exists",
    "extra": {}
  }
}

Updated by Denis Kildishev 8 months ago · 54 revisions