Mercurial > hg > orthanc

comparison OrthancServer/Sources/OrthancRestApi/OrthancRestResources.cpp @ 4414:d928dfcacb4b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cont openapi
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 28 Dec 2020 14:46:51 +0100
parents 22a1352a0823
children b50410d0e98c
comparison
equal deleted inserted replaced
4413:22a1352a0823 4414:d928dfcacb4b
511 } 511 }
512 512
513 513
514 static void ListFrames(RestApiGetCall& call) 514 static void ListFrames(RestApiGetCall& call)
515 { 515 {
516 if (call.IsDocumentation())
517 {
518 call.GetDocumentation()
519 .SetTag("Instances")
520 .SetSummary("List available frames")
521 .SetDescription("List the frames that are available in the DICOM instance of interest")
522 .SetUriArgument("id", "Orthanc identifier of the DICOM instance of interest")
523 .AddAnswerType(MimeType_Json, "The list of the indices of the available frames")
524 .SetHttpGetSample("https://demo.orthanc-server.com/instances/7c92ce8e-bbf67ed2-ffa3b8c1-a3b35d94-7ff3ae26/frames", true);
525 return;
526 }
527
516 std::string publicId = call.GetUriComponent("id", ""); 528 std::string publicId = call.GetUriComponent("id", "");
517 529
518 unsigned int numberOfFrames; 530 unsigned int numberOfFrames;
519 531
520 { 532 {
1173 } 1185 }
1174 1186
1175 1187
1176 static void GetMatlabImage(RestApiGetCall& call) 1188 static void GetMatlabImage(RestApiGetCall& call)
1177 { 1189 {
1190 if (call.IsDocumentation())
1191 {
1192 std::string description;
1193
1194 if (call.HasUriComponent("frame"))
1195 {
1196 description = "Decode one frame of interest from the given DICOM instance";
1197 call.GetDocumentation()
1198 .SetUriArgument("frame", RestApiCallDocumentation::Type_Number, "Index of the frame (starts at `0`)");
1199 }
1200 else
1201 {
1202 description = "Decode the first frame of the given DICOM instance.";
1203 }
1204
1205 call.GetDocumentation()
1206 .SetTag("Instances")
1207 .SetSummary("Decode frame for Matlab")
1208 .SetDescription(description + ", and export this frame as a Octave/Matlab matrix to be imported with `eval()`: "
1209 "https://book.orthanc-server.com/faq/matlab.html")
1210 .SetUriArgument("id", "Orthanc identifier of the DICOM instance of interest")
1211 .AddAnswerType(MimeType_PlainText, "Octave/Matlab matrix");
1212 return;
1213 }
1214
1178 Semaphore::Locker locker(throttlingSemaphore_); 1215 Semaphore::Locker locker(throttlingSemaphore_);
1179 1216
1180 ServerContext& context = OrthancRestApi::GetContext(call); 1217 ServerContext& context = OrthancRestApi::GetContext(call);
1181 1218
1182 std::string frameId = call.GetUriComponent("frame", "0"); 1219 std::string frameId = call.GetUriComponent("frame", "0");
1323 } 1360 }
1324 1361
1325 1362
1326 static void ListMetadata(RestApiGetCall& call) 1363 static void ListMetadata(RestApiGetCall& call)
1327 { 1364 {
1365 if (call.IsDocumentation())
1366 {
1367 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str());
1368 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */);
1369 call.GetDocumentation()
1370 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1371 .SetSummary("List metadata")
1372 .SetDescription("Get the list of metadata that are associated with the given " + r)
1373 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1374 .SetHttpGetArgument("expand", RestApiCallDocumentation::Type_String,
1375 "If present, also retrieve the value of the individual metadata", false)
1376 .AddAnswerType(MimeType_Json, "JSON array containing the names of the available metadata, "
1377 "or JSON associative array mapping metadata to their values (if `expand` argument is provided)")
1378 .SetHttpGetSample(GetDocumentationSampleResource(t) + "/metadata", true);
1379 return;
1380 }
1381
1328 CheckValidResourceType(call); 1382 CheckValidResourceType(call);
1329 1383
1330 std::string publicId = call.GetUriComponent("id", ""); 1384 std::string publicId = call.GetUriComponent("id", "");
1331 std::map<MetadataType, std::string> metadata; 1385 std::map<MetadataType, std::string> metadata;
1332 1386
1360 } 1414 }
1361 1415
1362 1416
1363 static void GetMetadata(RestApiGetCall& call) 1417 static void GetMetadata(RestApiGetCall& call)
1364 { 1418 {
1419 if (call.IsDocumentation())
1420 {
1421 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str());
1422 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */);
1423 call.GetDocumentation()
1424 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1425 .SetSummary("Get metadata")
1426 .SetDescription("Get the value of a metadata that is associated with the given " + r)
1427 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1428 .SetUriArgument("name", "The name of the metadata, or its index (cf. `UserMetadata` configuration option)")
1429 .AddAnswerType(MimeType_PlainText, "Value of the metadata");
1430 return;
1431 }
1432
1365 CheckValidResourceType(call); 1433 CheckValidResourceType(call);
1366 1434
1367 std::string publicId = call.GetUriComponent("id", ""); 1435 std::string publicId = call.GetUriComponent("id", "");
1368 std::string name = call.GetUriComponent("name", ""); 1436 std::string name = call.GetUriComponent("name", "");
1369 MetadataType metadata = StringToMetadata(name); 1437 MetadataType metadata = StringToMetadata(name);
1376 } 1444 }
1377 1445
1378 1446
1379 static void DeleteMetadata(RestApiDeleteCall& call) 1447 static void DeleteMetadata(RestApiDeleteCall& call)
1380 { 1448 {
1449 if (call.IsDocumentation())
1450 {
1451 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str());
1452 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */);
1453 call.GetDocumentation()
1454 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1455 .SetSummary("Delete metadata")
1456 .SetDescription("Delete some metadata associated with the given DICOM " + r +
1457 ". This call will fail if trying to delete a system metadata (i.e. whose index is < 1024).")
1458 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1459 .SetUriArgument("name", "The name of the metadata, or its index (cf. `UserMetadata` configuration option)");
1460 return;
1461 }
1462
1381 CheckValidResourceType(call); 1463 CheckValidResourceType(call);
1382 1464
1383 std::string publicId = call.GetUriComponent("id", ""); 1465 std::string publicId = call.GetUriComponent("id", "");
1384 std::string name = call.GetUriComponent("name", ""); 1466 std::string name = call.GetUriComponent("name", "");
1385 MetadataType metadata = StringToMetadata(name); 1467 MetadataType metadata = StringToMetadata(name);
1396 } 1478 }
1397 1479
1398 1480
1399 static void SetMetadata(RestApiPutCall& call) 1481 static void SetMetadata(RestApiPutCall& call)
1400 { 1482 {
1483 if (call.IsDocumentation())
1484 {
1485 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str());
1486 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */);
1487 call.GetDocumentation()
1488 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1489 .SetSummary("Set metadata")
1490 .SetDescription("Set the value of some metadata in the given DICOM " + r +
1491 ". This call will fail if trying to modify a system metadata (i.e. whose index is < 1024).")
1492 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1493 .SetUriArgument("name", "The name of the metadata, or its index (cf. `UserMetadata` configuration option)")
1494 .AddRequestType(MimeType_PlainText, "String value of the metadata");
1495 return;
1496 }
1497
1401 CheckValidResourceType(call); 1498 CheckValidResourceType(call);
1402 1499
1403 std::string publicId = call.GetUriComponent("id", ""); 1500 std::string publicId = call.GetUriComponent("id", "");
1404 std::string name = call.GetUriComponent("name", ""); 1501 std::string name = call.GetUriComponent("name", "");
1405 MetadataType metadata = StringToMetadata(name); 1502 MetadataType metadata = StringToMetadata(name);
1475 { 1572 {
1476 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str()); 1573 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str());
1477 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */); 1574 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */);
1478 call.GetDocumentation() 1575 call.GetDocumentation()
1479 .SetTag("Other") 1576 .SetTag("Other")
1480 .SetSummary("List of operations on attachments") 1577 .SetSummary("List operations on attachments")
1481 .SetDescription("Get the list of operations that are available for attachments associated with the given " + r) 1578 .SetDescription("Get the list of the operations that are available for attachments associated with the given " + r)
1482 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1579 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1483 .SetUriArgument("name", "The name of the attachment") 1580 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1484 .AddAnswerType(MimeType_Json, "List of the available operations") 1581 .AddAnswerType(MimeType_Json, "List of the available operations")
1485 .SetHttpGetSample("https://demo.orthanc-server.com/instances/d94d9a03-3003b047-a4affc69-322313b2-680530a2/attachments/dicom", true); 1582 .SetHttpGetSample("https://demo.orthanc-server.com/instances/d94d9a03-3003b047-a4affc69-322313b2-680530a2/attachments/dicom", true);
1486 return; 1583 return;
1487 } 1584 }
1488 1585
1533 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1630 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1534 .SetSummary("Get attachment" + std::string(uncompress ? "" : " (no decompression)")) 1631 .SetSummary("Get attachment" + std::string(uncompress ? "" : " (no decompression)"))
1535 .SetDescription("Get the (binary) content of one attachment associated with the given " + r + 1632 .SetDescription("Get the (binary) content of one attachment associated with the given " + r +
1536 std::string(uncompress ? "" : ". The attachment will not be decompressed if `StorageCompression` if `true`.")) 1633 std::string(uncompress ? "" : ". The attachment will not be decompressed if `StorageCompression` if `true`."))
1537 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1634 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1538 .SetUriArgument("name", "The name of the attachment") 1635 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1539 .AddAnswerType(MimeType_Binary, "The attachment"); 1636 .AddAnswerType(MimeType_Binary, "The attachment");
1540 return; 1637 return;
1541 } 1638 }
1542 1639
1543 ServerContext& context = OrthancRestApi::GetContext(call); 1640 ServerContext& context = OrthancRestApi::GetContext(call);
1570 call.GetDocumentation() 1667 call.GetDocumentation()
1571 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1668 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1572 .SetSummary("Get size of attachment") 1669 .SetSummary("Get size of attachment")
1573 .SetDescription("Get the size of one attachment associated with the given " + r) 1670 .SetDescription("Get the size of one attachment associated with the given " + r)
1574 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1671 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1575 .SetUriArgument("name", "The name of the attachment") 1672 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1576 .AddAnswerType(MimeType_PlainText, "The size of the attachment"); 1673 .AddAnswerType(MimeType_PlainText, "The size of the attachment");
1577 return; 1674 return;
1578 } 1675 }
1579 1676
1580 FileInfo info; 1677 FileInfo info;
1595 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1692 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1596 .SetSummary("Get size of attachment on disk") 1693 .SetSummary("Get size of attachment on disk")
1597 .SetDescription("Get the size of one attachment associated with the given " + r + ", as stored on the disk. " 1694 .SetDescription("Get the size of one attachment associated with the given " + r + ", as stored on the disk. "
1598 "This is different from `.../size` iff `EnableStorage` is `true`.") 1695 "This is different from `.../size` iff `EnableStorage` is `true`.")
1599 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1696 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1600 .SetUriArgument("name", "The name of the attachment") 1697 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1601 .AddAnswerType(MimeType_PlainText, "The size of the attachment, as stored on the disk"); 1698 .AddAnswerType(MimeType_PlainText, "The size of the attachment, as stored on the disk");
1602 return; 1699 return;
1603 } 1700 }
1604 1701
1605 FileInfo info; 1702 FileInfo info;
1619 call.GetDocumentation() 1716 call.GetDocumentation()
1620 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1717 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1621 .SetSummary("Get MD5 of attachment") 1718 .SetSummary("Get MD5 of attachment")
1622 .SetDescription("Get the MD5 hash of one attachment associated with the given " + r) 1719 .SetDescription("Get the MD5 hash of one attachment associated with the given " + r)
1623 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1720 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1624 .SetUriArgument("name", "The name of the attachment") 1721 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1625 .AddAnswerType(MimeType_PlainText, "The MD5 of the attachment"); 1722 .AddAnswerType(MimeType_PlainText, "The MD5 of the attachment");
1626 return; 1723 return;
1627 } 1724 }
1628 1725
1629 FileInfo info; 1726 FileInfo info;
1645 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1742 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1646 .SetSummary("Get MD5 of attachment on disk") 1743 .SetSummary("Get MD5 of attachment on disk")
1647 .SetDescription("Get the MD5 hash of one attachment associated with the given " + r + ", as stored on the disk. " 1744 .SetDescription("Get the MD5 hash of one attachment associated with the given " + r + ", as stored on the disk. "
1648 "This is different from `.../md5` iff `EnableStorage` is `true`.") 1745 "This is different from `.../md5` iff `EnableStorage` is `true`.")
1649 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1746 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1650 .SetUriArgument("name", "The name of the attachment") 1747 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1651 .AddAnswerType(MimeType_PlainText, "The MD5 of the attachment, as stored on the disk"); 1748 .AddAnswerType(MimeType_PlainText, "The MD5 of the attachment, as stored on the disk");
1652 return; 1749 return;
1653 } 1750 }
1654 1751
1655 FileInfo info; 1752 FileInfo info;
1670 call.GetDocumentation() 1767 call.GetDocumentation()
1671 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1768 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1672 .SetSummary("Verify attachment") 1769 .SetSummary("Verify attachment")
1673 .SetDescription("Verify that the attachment is not corrupted, by validating its MD5 hash") 1770 .SetDescription("Verify that the attachment is not corrupted, by validating its MD5 hash")
1674 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1771 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1675 .SetUriArgument("name", "The name of the attachment") 1772 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1676 .AddAnswerType(MimeType_Json, "On success, a valid JSON object is returned"); 1773 .AddAnswerType(MimeType_Json, "On success, a valid JSON object is returned");
1677 return; 1774 return;
1678 } 1775 }
1679 1776
1680 ServerContext& context = OrthancRestApi::GetContext(call); 1777 ServerContext& context = OrthancRestApi::GetContext(call);
1729 } 1826 }
1730 1827
1731 1828
1732 static void UploadAttachment(RestApiPutCall& call) 1829 static void UploadAttachment(RestApiPutCall& call)
1733 { 1830 {
1831 if (call.IsDocumentation())
1832 {
1833 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str());
1834 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */);
1835 call.GetDocumentation()
1836 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1837 .SetSummary("Set attachment")
1838 .SetDescription("Attach a file to the given DICOM " + r +
1839 ". This call will fail if trying to modify a system attachment (i.e. whose index is < 1024).")
1840 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1841 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1842 .AddRequestType(MimeType_Binary, "Binary data containing the attachment")
1843 .AddAnswerType(MimeType_Json, "Empty JSON object in the case of a success");
1844 return;
1845 }
1846
1734 ServerContext& context = OrthancRestApi::GetContext(call); 1847 ServerContext& context = OrthancRestApi::GetContext(call);
1735 CheckValidResourceType(call); 1848 CheckValidResourceType(call);
1736 1849
1737 std::string publicId = call.GetUriComponent("id", ""); 1850 std::string publicId = call.GetUriComponent("id", "");
1738 std::string name = call.GetUriComponent("name", ""); 1851 std::string name = call.GetUriComponent("name", "");
1757 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str()); 1870 ResourceType t = StringToResourceType(call.GetFullUri()[0].c_str());
1758 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */); 1871 std::string r = GetResourceTypeText(t, false /* plural */, false /* upper case */);
1759 call.GetDocumentation() 1872 call.GetDocumentation()
1760 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1873 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1761 .SetSummary("Delete attachment") 1874 .SetSummary("Delete attachment")
1762 .SetDescription("Delete an attachment associated with the given DICOM " + r) 1875 .SetDescription("Delete an attachment associated with the given DICOM " + r +
1876 ". This call will fail if trying to delete a system attachment (i.e. whose index is < 1024).")
1763 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1877 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1764 .SetUriArgument("name", "The name of the attachment"); 1878 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)");
1765 return; 1879 return;
1766 } 1880 }
1767 1881
1768 CheckValidResourceType(call); 1882 CheckValidResourceType(call);
1769 1883
1816 call.GetDocumentation() 1930 call.GetDocumentation()
1817 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1931 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1818 .SetSummary(compression == CompressionType_None ? "Uncompress attachment" : "Compress attachment") 1932 .SetSummary(compression == CompressionType_None ? "Uncompress attachment" : "Compress attachment")
1819 .SetDescription("Change the compression scheme that is used to store an attachment.") 1933 .SetDescription("Change the compression scheme that is used to store an attachment.")
1820 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1934 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1821 .SetUriArgument("name", "The name of the attachment"); 1935 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)");
1822 return; 1936 return;
1823 } 1937 }
1824 1938
1825 CheckValidResourceType(call); 1939 CheckValidResourceType(call);
1826 1940
1842 call.GetDocumentation() 1956 call.GetDocumentation()
1843 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */)) 1957 .SetTag(GetResourceTypeText(t, true /* plural */, true /* upper case */))
1844 .SetSummary("Is attachment compressed?") 1958 .SetSummary("Is attachment compressed?")
1845 .SetDescription("Test whether the attachment has been stored as a compressed file on the disk.") 1959 .SetDescription("Test whether the attachment has been stored as a compressed file on the disk.")
1846 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest") 1960 .SetUriArgument("id", "Orthanc identifier of the " + r + " of interest")
1847 .SetUriArgument("name", "The name of the attachment") 1961 .SetUriArgument("name", "The name of the attachment, or its index (cf. `UserContentType` configuration option)")
1848 .AddAnswerType(MimeType_PlainText, "`0` if the attachment was stored uncompressed, `1` if it was compressed"); 1962 .AddAnswerType(MimeType_PlainText, "`0` if the attachment was stored uncompressed, `1` if it was compressed");
1849 return; 1963 return;
1850 } 1964 }
1851 1965
1852 FileInfo info; 1966 FileInfo info;