Project

General

Profile

APIForNG » History » Version 20

Denis Kildishev, 02/11/2021 09:12 PM

1 1 Denis Kildishev
h1. APIForNG
2 4 Denis Kildishev
3 1 Denis Kildishev
По текущей модели предполагается использование следующих методов:
4 2 Denis Kildishev
Для всех методов по умолчанию используется один заголовочный параметр
5
Authorization со значением Bearer 36AC0A0F7F271314B72986EB54DB2343
6 1 Denis Kildishev
7
1.Получение списка проектов
8
Method:
9
GET
10
Path:
11
http://localhost:9988/projects
12 2 Denis Kildishev
Без дополнительных параметров
13
Пример выдачи
14 8 Alexey Khoroshilov
<pre><code class="javascript">
15 1 Denis Kildishev
{
16
  "success" : true,
17
  "result" : {
18
    "projects" : [ "Example", "з1", "arch", "stpo"],
19 10 Denis Kildishev
    "count" : 4
20 1 Denis Kildishev
  }
21
}
22 8 Alexey Khoroshilov
</code></pre>
23
24 2 Denis Kildishev
Без дополнительных параметров
25 1 Denis Kildishev
26 2 Denis Kildishev
2. Получение содержимого проекта(иерархия), для expandable - ограниченное 1м уровнем 
27 1 Denis Kildishev
Method:
28
GET
29
Path:
30 2 Denis Kildishev
http://localhost:9988/projects/{arch}[/expandable]
31
Здесь {arch} - имя проекта, на данный момент регистрозависимо
32
Без дополнительных параметров
33
Пример выдачи
34 9 Denis Kildishev
<pre><code class="javascript">
35 1 Denis Kildishev
{
36 9 Denis Kildishev
  "success": true,
37
  "result": {
38
    "name": "arch",
39
    "nodes": [
40
      {
41
        "uuid": "243f4afe-1d28-4652-80b9-4ad123b415a4"
42
        "name": "Documents",
43
        "type": "DocFolder",
44 1 Denis Kildishev
45 9 Denis Kildishev
      },
46
      {
47
        "uuid": "7a5374ee-eb7a-4731-997d-5f52f00ebc2e"
48
        "name": "Requirements",
49
        "type": "Requirement",
50
        "haveChildren":"true",
51
        "children": [
52
          {
53
            "uuid": "8ccd86e3-5689-43aa-9241-04728447e8f7",
54
            "name": "001",
55
            "type": "Requirement",
56
            "children": [],
57
          }
58
        ]
59
      },
60
      {
61
        "uuid": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85",
62
        "name": "Reports",
63
        "type": "ReportFolder"
64
      }
65
    ],
66
  }
67 1 Denis Kildishev
}
68 9 Denis Kildishev
</code></pre>
69 1 Denis Kildishev
по умолчанию выдает все дерево с базовым набором из нескольких полей - уникального id uuid, отображаемого имени name, типа type и массива потомков children. 
70
поле haveChildren присутствует если у узла есть потомки и работает даже когда children не видны в режиме expandable для 2 уровня вложенности
71
при режиме [expandable] потомки выдаются до 1 уровня вложенности
72
73
3. Получение данных по поддереву
74
Method:
75
GET
76
Path:
77
http://localhost:9988/projects/{TEST}/hierarchy/ff42a6f4-f9ac-48c3-b41c-c36395df8a85[/expandable]
78
{TEST} - имя проекта
79
id после /hierarchy это id узла для которого получается поддерево, режим /expandable работает аналогично проекту
80
Без дополнительных параметров
81
Пример выдачи
82 9 Denis Kildishev
<pre><code class="javascript">
83 1 Denis Kildishev
{
84 9 Denis Kildishev
  "success": true, 
85
  "result": 
86
  {
87
    "uuid": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85",
88
    "name": "Reports",
89
    "type": "ReportFolder",
90
    "parent": "ff42a6f4-f9ac-48c3-b41c-c36395df8a85"
91
  }
92 1 Denis Kildishev
}
93 9 Denis Kildishev
</code></pre>
94 1 Denis Kildishev
Содержимое result аналогично описанию одного узла и всех его потомков[или потомков 1 уровня вложенности для expandable] в выдаче проекта
95
96
4. Получение свойств узлов
97
Method:
98
POST
99
Path:
100
http://localhost:9988/projects/TEST/getattributes/
101
В теле запроса передаются все uuid ы узлов для которых нужно выдать свойства. Конкретная реализация пока уточняется, текущее предположение - просто передавать в текстовом виде с разделителем ;. Возможно будут передаваться в качестве массива по аналогии с передачей данных форм. Пример "4db0fbf4-f383-4740-9d72-891ef112f742;ff42a6f4-f9ac-48c3-b41c-c36395df8a85".
102
Пример выдачи
103 9 Denis Kildishev
<pre><code class="javascript">
104 1 Denis Kildishev
{
105 9 Denis Kildishev
  "success": true,
106
  "result": {
107
    "attributes": {
108
      "4db0fbf4-f383-4740-9d72-891ef112f742":{
109
        "Вид": {
110
          "value": "",
111
          "type": "STRING"
112
        },
113
        "_index": {
114
          "value": "1",
115
          "type": "STRING"
116
        },
117
        "_name": {
118
          "value": "Хронология",
119
          "type": "STRING"
120
        },
121
        "_type": {
122
          "value": "Requirement",
123
          "type": "STRING"
124
        },
125
        "_id": {
126
          "value": "001",
127
          "type": "STRING"
128
        },
129
        "ForeignID": {
130
          "value": "1",
131
          "type": "STRING"
132
        }
133
      },
134
      "9dffaddf-a55a-4fa1-a3bc-4a5fade4169f":{
135
        "Вид": {
136
          "value": "Заголовок",
137
          "enumName": "Вид",
138
          "valueType": "STRING",
139
          "type": "ENUM"
140
        },
141
        "_index": {
142
          "value": "1",
143
          "type": "STRING"
144
        },
145
        "_tags": {
146
          "value": [
147
            {
148
              "value": "section_Архитектура_ПО_Поток_управления"
149
            }
150
          ],
151
          "valuesType": "STRING",
152
          "type": "LIST"
153
        },
154
        "_type": {
155
          "value": "Requirement",
156
          "type": "STRING"
157
        },
158
        "_id": {
159
          "value": "Поток управления",
160
          "type": "STRING"
161
        },
162
        "_description": {
163
          "value": " ",
164
          "type": "HTML"
165
        },
166
        "ForeignID": {
167
          "value": "2",
168
          "type": "STRING"
169
        }
170
      }
171
    }
172
  }
173 3 Denis Kildishev
}
174 9 Denis Kildishev
</code></pre>
175 3 Denis Kildishev
176
В примере выдача свойств двух узлов. Они расположены в result в виде словаря где ключ это id а значение - набор свойств узла.
177
178
5. Метод для работы с ресурсами. Текущая реализация
179
Method:
180
GET
181
Path:
182
http://localhost:9988/projects/{TEST}/nodes/{n}/resources/{resFolder}/{res}
183
{Test} имя проекта
184
{n} - uuid узла
185
{resFolder} папка с ресурсами(внутри {node_id}_resources, например "images")
186 4 Denis Kildishev
{res} имя файла
187
Возвращает ответ типа APPLICATION_OCTET_STREAM включающий в себя содержимое нужного ресурса. В теле также передается имя файла.
188
Если ресурса нет то выдается ответ NOT_FOUND типа plain text
189
Если передано некорректное имя папки с ресурсами(включающее недопустимые символы) то выдается ответ INVALID FOLDER типа plain text
190
191 1 Denis Kildishev
Предположительно появится метод получения ресурсов по списку для множества узлов но потом
192
Возможный формат передачи данных - json пары
193 9 Denis Kildishev
<pre><code class="javascript">
194 1 Denis Kildishev
{"uuid":"resfolder/resname","uuid2":"resfolder2/resname2"}
195 9 Denis Kildishev
</code></pre>
196 1 Denis Kildishev
Возможный тип возвращаемого значения - multipart/mixed. Но при этом размер возвращаемых данных может оказаться значительным
197 11 Denis Kildishev
198
6. Метод для получения связей
199
Method:
200
POST
201
Path:
202
http://localhost:9988/projects/{TEST}/getlinks
203
В теле запроса передаются все uuid ы узлов для которых нужно выдать свойства. Текущее предположение - в текстовом виде с разделителем ';'. Пример "4db0fbf4-f383-4740-9d72-891ef112f742;ff42a6f4-f9ac-48c3-b41c-c36395df8a85".
204
Результат включает в себя аналог словаря uuid:{ссылки}. Если для узла ссылок нет то в выдачу он не попадает.
205
ссылки разбиты на 4 раздела
206
linkToRelations - исходящие ссылки по свойствам
207
linkedByRelations - входящие ссылки по свойствам
208
linkToTerms - связи от использования термина из другого узла к определению в данном узле
209
linkedByTerms - связи от использования термина из данного узла к определению в другом узле
210
Пример выдачи
211
<pre><code class="javascript">
212
{
213
  "success": true,
214
  "result": {
215
    "links": {
216
      "7a5374ee-eb7a-4731-997d-5f52f00ebc2e": {
217
        "linkToRelations": {
218
          "reg": [
219
            {
220
              "haveChildren": true,
221
              "name": "Архитектура ПО",
222
              "type": "Requirement",
223
              "parent": "7a5374ee-eb7a-4731-997d-5f52f00ebc2e",
224
              "externalId": "9",
225
              "uuid": "188f8992-12e1-4acc-bf5a-fd568b1a2161"
226
            }
227
          ],
228
        },
229
        "linkedByRelations": {
230
          "d": [
231
            {
232
              "haveChildren": true,
233
              "name": "если E = 2 k -1",
234
              "type": "Requirement",
235
              "project": "SQRT",
236
              "parent": "ba51211b-d1c6-46ae-9333-bdad409b1fdb",
237
              "uuid": "127bfded-ae30-4365-9274-c116201a4ac1"
238
            },
239
            {
240
              "name": "001",
241
              "type": "Requirement",
242
              "project": "SQRT",
243
              "parent": "ebc37a22-15c5-482d-9e4c-8c23461fca39",
244
              "uuid": "57b80f94-9011-43d8-844f-5bef23e37afb"
245
            },
246
            {
247
              "name": "002",
248
              "type": "Requirement",
249
              "project": "SQRT",
250
              "parent": "4b40ef1a-de18-4d71-8825-2ef16b502cd0",
251
              "uuid": "658b8768-55b8-45b5-99b3-f03ba252acb7"
252
            }
253
          ]
254
        }
255
      }
256
    }
257
  }
258
} 
259
</code></pre>
260 12 Denis Kildishev
261
7. Установка свойств
262
Method:
263
POST
264
Datatype:
265 14 Denis Kildishev
multipart/form-data или application/json
266 12 Denis Kildishev
Path:
267 1 Denis Kildishev
http://localhost:9988/projects/{TEST}/nodes/{uuid_of_node}/attributes/
268 17 Denis Kildishev
В теле запроса передаются значения свойств которые требуется изменить. Пример запроса ниже. Значение свойств которые не переданы в запросе остаются неизмеными. Сами свойства передаются через application/json поле "input". Изображения передаются в виде прикрепленных файлов в поле images.//TODO добавить пример.
269 14 Denis Kildishev
При использовании типа application/json вместо multipart/form-data свойства передаются непосредственно в теле запроса
270 12 Denis Kildishev
<pre><code class="javascript">
271
{
272
  "attributes":
273
    {
274
      "test":
275
        {
276
          "value":"2"
277
        },
278
      "test2":
279
        {
280
          "value":"3", "type": "INT"
281
        }
282
    }
283
}
284
</code></pre>
285
Возвращает текущий набор видимых распологающихся в узле свойств
286
<pre><code class="javascript">
287
{
288
  "success": true,
289
  "result": {
290
    "attributes": {
291
      "test2": {
292
        "value": "3",
293
        "type": "INT"
294
      },
295
      "_index": {
296
        "value": "8",
297
        "type": "STRING"
298
      },
299
      "test": {
300
        "value": "2",
301
        "type": "STRING"
302
      },
303
      "_tags": {
304
        "valuesType": "STRING",
305
        "value": [
306
          {
307
            "value": "section_Архитектура_ПО"
308
          }
309
        ],
310
        "type": "LIST"
311
      },
312
      "_type": {
313
        "value": "Requirement",
314
        "type": "STRING"
315
      },
316
      "_id": {
317
        "value": "Архитектура ПО",
318
        "type": "STRING"
319
      }
320
    }
321
  }
322
}
323
</code></pre>
324
325
8. Замена свойств
326
Аналогичен 7, отличается использованием метода PUT. Удаляет все свойства которые не перечисленны в запросе
327
328
9. Удаление свойств
329
Method:
330
DELETE
331
Path:
332
http://localhost:9988/projects/{TEST}/nodes/{n}/attributes/
333
{TEST} - имя проекта
334
{n} - uuid узла
335
В теле запроса передаются все имена свойств которые требуется удалить в текстовом виде с разделителем ';'. Пример
336
_name;attributeName
337
Результат включают в себя список оставшихся свойств. 
338
Пример выдачи
339
340
<pre><code class="javascript">
341
{
342 13 Denis Kildishev
  "success": true,
343
  "result": {
344
    "attributes": [
345
      "Вид",
346
      "Производное",
347
      "_index",
348
      "_tags",
349
      "_type",
350
      "_id",
351
      "ForeignID"
352
    ],
353
  }
354 1 Denis Kildishev
}
355
</code></pre>
356 14 Denis Kildishev
357 15 Denis Kildishev
10. Создание проекта
358
Method:
359
PUT
360
Path:
361
http://localhost:9988/projects/{new_name}
362
{new_name} - имя проекта
363
Возвращает 
364
<pre><code class="javascript">
365
{
366
  "success": true,
367
  "result": {}
368
}
369
</code></pre>
370
либо если проект уже существует 
371
<pre><code class="javascript">
372
{
373
  "success": false,
374
  "error": {
375
    "code": "project_exists",
376
    "message": "Specified project already exists",
377
    "extra": {}
378
  }
379
}
380
</code></pre>
381 16 Denis Kildishev
382
10. Удаление проекта
383
Method:
384
DELETE
385
Path:
386
http://localhost:9988/projects/{name}
387
{name} - имя проекта
388
Возвращает 
389
<pre><code class="javascript">
390
{
391
  "success": true,
392
  "result": {}
393
}
394
</code></pre>
395
либо если проект не найден
396
<pre><code class="javascript">
397
{
398
  "success": false,
399
  "error": {
400
    "code": "project_not_found",
401
    "message": "Specified project does not exists",
402
    "extra": {}
403
  }
404
}
405 1 Denis Kildishev
</code></pre>
406 17 Denis Kildishev
407
11. Создание узла
408
Method:
409
PUT
410
Path:
411
http://localhost:9988/projects/{project_name}/create
412
project_name - имя проекта
413
Datatype:
414 19 Denis Kildishev
multipart/form-data или application/json
415
Для multipart/form-data в теле содержится два поля - input содержит json с описанием узла, images содержит изображения.
416
Для application/json в теле содержится только json с описанием
417 17 Denis Kildishev
<pre><code class="javascript">
418
{
419
  "parent": "516bbbbc-babf-45d6-a146-61db334411be",
420
  "type":"Requirement",
421
  "id":"002",
422
  "attributes":{
423
    "test": {
424
      "value": "13d23",
425
      "type": "INT"
426
    },
427
    "_name": {
428
      "value": "{test} test 123"
429
    },
430
    "Ref": {
431
      "type": "REFERENCE",
432
      "value":"test"
433
    },
434
    "_description": {
435
      "value":"test desc <img src='strange.png' alt='strange.xcf'/>", "type":"HTML"
436
    }
437
  }
438
}
439
</code>
440
</pre>
441
id является опциональным, если его не указывать он будет формироваться автоматически
442
Пример возвращаемого значения
443
<pre><code class="javascript">
444
{
445
  "success": true,
446
  "result": {
447
    "name": "13d23 test 123",
448
    "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3",
449
    "parent": "1f6e9e4f-4f63-446b-bddd-15838c15c212",
450
    "attributes": {
451
      "Ref": {
452
        "value": "*Missing(Ref): 'test'",
453
        "type": "REFERENCE"
454
      },
455
      "test": {
456
        "value": "13d23",
457
        "type": "INT"
458
      },
459
      "_name": {
460
        "value": "13d23 test 123",
461
        "type": "STRING"
462
      },
463
      "_type": {
464
        "value": "Requirement",
465
        "type": "STRING"
466
      },
467
      "_id": {
468
        "value": "002",
469
        "type": "STRING"
470
      },
471
      "_description": {
472
        "value": "test desc <img src='strange.png' alt='strange.xcf'/>",
473
        "type": "HTML"
474
      }
475
    }
476
  }
477
}
478
</code>
479
</pre>
480 18 Denis Kildishev
481 1 Denis Kildishev
12. Удаление узла
482 18 Denis Kildishev
Method:
483 19 Denis Kildishev
DELETE
484 18 Denis Kildishev
Path:
485
http://localhost:9988/projects/{project_name}/node
486
project_name - имя проекта
487
В теле в виде текста содержится идентефикатор узла, например UUID, но можно использовать и другие способы идентефикации
488
Пример
489
<pre><code class="javascript">
490
03745ff6-6f9f-4517-b011-c92ca6081a47
491
</code>
492
</pre>
493
Пример удачного удаления. Возвращается иерархия на уровне родителя удаленного узла
494
<pre><code class="javascript">
495
{
496
  "success": true,
497
  "result": {
498
    "haveChildren": true,
499
    "name": "Requirements",
500
    "type": "Requirement",
501
    "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212",
502
    "children": [
503
      {
504
        "name": "002",
505
        "type": "Requirement",
506
        "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3"
507
      },
508
      {
509
        "name": "004",
510
        "type": "Requirement",
511
        "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18"
512
      },
513
      {
514
        "name": "005",
515
        "type": "Requirement",
516
        "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318"
517
      },
518 1 Denis Kildishev
      {
519 20 Denis Kildishev
<pre><code class="javascript">
520
{
521
  "success": true,
522
  "result": {
523
    "haveChildren": true,
524
    "name": "Requirements",
525
    "type": "Requirement",
526
    "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212",
527
    "children": [
528
      {
529
        "name": "002",
530
        "type": "Requirement",
531
        "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3"
532
      },
533
      {
534
        "name": "004",
535
        "type": "Requirement",
536
        "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18"
537
      },
538
      {
539
        "name": "005",
540
        "type": "Requirement",
541
        "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318"
542
      },
543
      {
544 18 Denis Kildishev
       "name": "006",
545
       "type": "Requirement",
546
       "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2"
547
      },
548
      {
549
        "name": "007",
550
        "type": "Requirement",
551
        "uuid": "40155667-942e-43a6-9861-3c5b05adccfb"
552
      },
553
    ],
554
  }
555 1 Denis Kildishev
}
556 20 Denis Kildishev
       "name": "006",
557
       "type": "Requirement",
558
       "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2"
559
      },
560
      {
561
        "name": "007",
562
        "type": "Requirement",
563
        "uuid": "40155667-942e-43a6-9861-3c5b05adccfb"
564
      },
565
    ],
566
  }
567
}
568 18 Denis Kildishev
</code>
569
</pre>
570
Пример с отсутствующим узлом
571
<pre><code class="javascript">
572
{
573
  "success": false,
574
  "error": {
575
    "code": "qid_not_found",
576
    "message": "Specified QID does not exists",
577
    "extra": {}
578
  }
579
}
580
</code>
581 1 Denis Kildishev
</pre>
582 20 Denis Kildishev
583
13. Перемещение узла
584
Method:
585
POST
586
Path:
587
http://localhost:9988/projects/{project_name}/nodes/{uuid}/move
588
project_name - имя проекта
589
uuid - идентефикатор узла который требуется переместить
590
В теле содержится json с описанием параметров переноса
591
Пример
592
<pre><code class="javascript">
593
{
594
  "parent":"2ce727b8-0740-4344-988f-3155d7cea5f2",
595
  "node":"90ae2683-d4c7-4a97-ae03-255f449f9318",
596
  "position":"1"
597
}
598
</code>
599
</pre>
600
parent - указание на нового родителя
601
node и position - опциональные поля для того чтобы переместить узел в определенное место, могут не включаться в запрос
602
node при указании задает узел относительно которого нужно определить новую позицию
603
position может принимать значение <0 или >=1. Если он <0 то узел будет перемещен на позицию до целевого узла, если >=0 то после.
604
Пример удачного удаления. Возвращается иерархия на уровне нового родителя узла
605
<pre><code class="javascript">
606
{
607
  "success": true,
608
  "result": {
609
    "haveChildren": true,
610
    "name": "Requirements",
611
    "type": "Requirement",
612
    "uuid": "1f6e9e4f-4f63-446b-bddd-15838c15c212",
613
    "children": [
614
      {
615
        "name": "002",
616
        "type": "Requirement",
617
        "uuid": "fbc83670-6993-4baf-8c8c-0b98aaab8ab3"
618
      },
619
      {
620
        "name": "004",
621
        "type": "Requirement",
622
        "uuid": "fb594248-0739-4b74-9c82-7c6d84e09e18"
623
      },
624
      {
625
        "name": "005",
626
        "type": "Requirement",
627
        "uuid": "90ae2683-d4c7-4a97-ae03-255f449f9318"
628
      },
629
      {
630
       "name": "006",
631
       "type": "Requirement",
632
       "uuid": "2ce727b8-0740-4344-988f-3155d7cea5f2"
633
      },
634
      {
635
        "name": "007",
636
        "type": "Requirement",
637
        "uuid": "40155667-942e-43a6-9861-3c5b05adccfb"
638
      },
639
    ],
640
  }
641
}