APIForNG » History » Revision 20
Revision 19 (Denis Kildishev, 02/11/2021 08:59 PM) → Revision 20/54 (Denis Kildishev, 02/11/2021 09: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", "type": "DocFolder", }, { "uuid": "7a5374ee-eb7a-4731-997d-5f52f00ebc2e" "name": "Requirements", "type": "Requirement", "haveChildren":"true", "children": [ { "uuid": "8ccd86e3-5689-43aa-9241-04728447e8f7", "name": "001", "type": "Requirement", "children": [], } ] }, { "uuid": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85", "name": "Reports", "type": "ReportFolder" } ], } } </code></pre> по умолчанию выдает все дерево с базовым набором из нескольких полей - уникального id uuid, отображаемого имени name, типа type и массива потомков children. поле haveChildren присутствует если у узла есть потомки и работает даже когда children не видны в режиме expandable для 2 уровня вложенности при режиме [expandable] потомки выдаются до 1 уровня вложенности 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", "type": "ReportFolder", "parent": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85" } } </code></pre> Содержимое result аналогично описанию одного узла и всех его потомков[или потомков 1 уровня вложенности для expandable] в выдаче проекта 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": "Архитектура ПО", "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", "type": "Requirement", "project": "SQRT", "parent": "ba51211b-d1c6-46ae-9333-bdad409b1fdb", "uuid": "127bfded-ae30-4365-9274-c116201a4ac1" }, { "name": "001", "type": "Requirement", "project": "SQRT", "parent": "ebc37a22-15c5-482d-9e4c-8c23461fca39", "uuid": "57b80f94-9011-43d8-844f-5bef23e37afb" }, { "name": "002", "type": "Requirement", "project": "SQRT", "parent": "4b40ef1a-de18-4d71-8825-2ef16b502cd0", "uuid": "658b8768-55b8-45b5-99b3-f03ba252acb7" } ] } } } } } </code></pre> 7. Установка свойств Method: POST 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> 8. Замена свойств Аналогичен 7, отличается использованием метода PUT. Удаляет все свойства которые не перечисленны в запросе 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", "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", "type": "Requirement", "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212", "children": [ { "name": "002", "type": "Requirement", "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3" }, { "name": "004", "type": "Requirement", "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18" }, { "name": "005", "type": "Requirement", "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318" }, { <pre><code class="javascript"> { "success": true, "result": { "haveChildren": true, "name": "Requirements", "type": "Requirement", "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212", "children": [ { "name": "002", "type": "Requirement", "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3" }, { "name": "004", "type": "Requirement", "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18" }, { "name": "005", "type": "Requirement", "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318" }, { "name": "006", "type": "Requirement", "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2" }, { "name": "007", "type": "Requirement", "uuid": "40155667-942e-43a6-9861-3c5b05adccfb" }, ], } } "name": "006", "type": "Requirement", "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2" }, { "name": "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", "type": "Requirement", "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212", "children": [ { "name": "002", "type": "Requirement", "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3" }, { "name": "004", "type": "Requirement", "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18" }, { "name": "005", "type": "Requirement", "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318" }, { "name": "006", "type": "Requirement", "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2" }, { "name": "007", "type": "Requirement", "uuid": "40155667-942e-43a6-9861-3c5b05adccfb" }, ], } }