APIForNG » History » Revision 33
Revision 32 (Denis Kildishev, 04/02/2021 02:14 PM) → Revision 33/54 (Denis Kildishev, 09/21/2021 10:12 PM)
h1. APIForNG
По текущей модели предполагается использование следующих методов:
Для всех методов по умолчанию используется один заголовочный параметр
Authorization со значением Bearer 36AC0A0F7F271314B72986EB54DB2343
1.Получение списка проектов
Method:
GET
Path:
http://localhost:9988/projects
Без дополнительных параметров
Пример выдачи
<pre><code class="javascript">
{
"success" : true,
"result" : {
"projects" : [ "Example", "з1", "arch", "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. Получение свойств узлов
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": "",
"type": "STRING"
},
"_index": {
"value": "1",
"type": "STRING"
},
"_name": {
"value": "Хронология",
"type": "STRING"
},
"_type": {
"value": "Requirement",
"type": "STRING"
},
"_id": {
"value": "001",
"type": "STRING"
},
"ForeignID": {
"value": "1",
"type": "STRING"
}
},
"9dffaddf-a55a-4fa1-a3bc-4a5fade4169f":{
"Вид": {
"value": "Заголовок",
"enumName": "Вид",
"valueType": "STRING",
"type": "ENUM"
},
"_index": {
"value": "1",
"type": "STRING"
},
"_tags": {
"value": [
{
"value": "section_Архитектура_ПО_Поток_управления"
}
],
"valuesType": "STRING",
"type": "LIST"
},
"_type": {
"value": "Requirement",
"type": "STRING"
},
"_id": {
"value": "Поток управления",
"type": "STRING"
},
"_description": {
"value": " ",
"type": "HTML"
},
"ForeignID": {
"value": "2",
"type": "STRING"
}
}
}
}
}
</code></pre>
В примере выдача свойств двух узлов. Они расположены в result в виде словаря где ключ это id а значение - набор свойств узла.
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. Установка свойств
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 свойства передаются непосредственно в теле запроса
<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">
{
"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>
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>