Project

General

Profile

Actions
History

Design » API »

APIForNG » History » Revision 20

« Previous | Revision 20/54 (diff) | Next »
Denis Kildishev, 02/11/2021 09:12 PM

APIForNG

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

1.Получение списка проектов
Method:
GET
Path:
http://localhost:9988/projects
Без дополнительных параметров
Пример выдачи

{
  "success" : true,
  "result" : {
    "projects" : [ "Example", "з1", "arch", "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",
        "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" 
      }
    ],
  }
}

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

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

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

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": "",
          "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" 
        }
      }
    }
  }
}

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

{"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": "Архитектура ПО",
              "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" 
            }
          ]
        }
      }
    }
  }
}

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 свойства передаются непосредственно в теле запроса

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

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

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",
    "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",
    "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" 
      },
      {
&lt;pre&gt;&lt;code class="javascript"&gt;
{
  "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" 
      },
    ],
  }
}
&lt;/code&gt;
&lt;/pre&gt;
Пример с отсутствующим узлом
&lt;pre&gt;&lt;code class="javascript"&gt;
{
  "success": false,
  "error": {
    "code": "qid_not_found",
    "message": "Specified QID does not exists",
    "extra": {}
  }
}
&lt;/code&gt;
&lt;/pre&gt;

13. Перемещение узла
Method:
POST
Path:
http://localhost:9988/projects/{project_name}/nodes/{uuid}/move
project_name - имя проекта
uuid - идентефикатор узла который требуется переместить
В теле содержится json с описанием параметров переноса
Пример
&lt;pre&gt;&lt;code class="javascript"&gt;
{
  "parent":"2ce727b8-0740-4344-988f-3155d7cea5f2",
  "node":"90ae2683-d4c7-4a97-ae03-255f449f9318",
  "position":"1" 
}
&lt;/code&gt;
&lt;/pre&gt;
parent - указание на нового родителя
node и position - опциональные поля для того чтобы переместить узел в определенное место, могут не включаться в запрос
node при указании задает узел относительно которого нужно определить новую позицию
position может принимать значение &lt;0 или &gt;=1. Если он &lt;0 то узел будет перемещен на позицию до целевого узла, если &gt;=0 то после.
Пример удачного удаления. Возвращается иерархия на уровне нового родителя узла
&lt;pre&gt;&lt;code class="javascript"&gt;
{
  "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" 
      },
    ],
  }
}

Updated by Denis Kildishev almost 4 years ago · 54 revisions