Mercurial > hg > orthanc

comparison OrthancServer/Sources/OrthancRestApi/OrthancRestSystem.cpp @ 4401:354ea95b294a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documenting system calls
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 23 Dec 2020 15:13:45 +0100
parents 85b5b0e1bac9
children ad646ff506d0
comparison
equal deleted inserted replaced
4400:029366f95217 4401:354ea95b294a
54 call.GetOutput().Redirect("app/explorer.html"); 54 call.GetOutput().Redirect("app/explorer.html");
55 } 55 }
56 56
57 static void GetSystemInformation(RestApiGetCall& call) 57 static void GetSystemInformation(RestApiGetCall& call)
58 { 58 {
59 if (call.IsDocumentation())
60 {
61 call.GetDocumentation()
62 .SetTag("System")
63 .SetSummary("Get system information")
64 .SetDescription("Get system information about Orthanc")
65 .SetAnswerField("ApiVersion", RestApiCallDocumentation::Type_Number, "Version of the REST API")
66 .SetAnswerField("Version", RestApiCallDocumentation::Type_String, "Version of Orthanc")
67 .SetAnswerField("DatabaseVersion", RestApiCallDocumentation::Type_Number,
68 "Version of the database: https://book.orthanc-server.com/developers/db-versioning.html")
69 .SetAnswerField("IsHttpServerSecure", RestApiCallDocumentation::Type_Boolean,
70 "Whether the REST API is properly secured (assuming no reverse proxy is in use): https://book.orthanc-server.com/faq/security.html#securing-the-http-server")
71 .SetAnswerField("StorageAreaPlugin", RestApiCallDocumentation::Type_String,
72 "Information about the installed storage area plugin (\"null\" if no such plugin is installed)")
73 .SetAnswerField("DatabaseBackendPlugin", RestApiCallDocumentation::Type_String,
74 "Information about the installed database index plugin (\"null\" if no such plugin is installed)")
75 .SetAnswerField("DicomAet", RestApiCallDocumentation::Type_String, "The DICOM AET of Orthanc")
76 .SetAnswerField("DicomPort", RestApiCallDocumentation::Type_Number, "The port to the DICOM server of Orthanc")
77 .SetAnswerField("HttpPort", RestApiCallDocumentation::Type_Number, "The port to the HTTP server of Orthanc")
78 .SetAnswerField("Name", RestApiCallDocumentation::Type_String,
79 "The name of the Orthanc server, cf. the \"Name\" configuration option")
80 .SetAnswerField("PluginsEnabled", RestApiCallDocumentation::Type_Boolean,
81 "Whether Orthanc was built with support for plugins")
82 .SetHttpGetSample("https://demo.orthanc-server.com/system", true);
83 return;
84 }
85
59 ServerContext& context = OrthancRestApi::GetContext(call); 86 ServerContext& context = OrthancRestApi::GetContext(call);
60 87
61 Json::Value result = Json::objectValue; 88 Json::Value result = Json::objectValue;
62 89
63 result["ApiVersion"] = ORTHANC_API_VERSION; 90 result["ApiVersion"] = ORTHANC_API_VERSION;
98 call.GetOutput().AnswerJson(result); 125 call.GetOutput().AnswerJson(result);
99 } 126 }
100 127
101 static void GetStatistics(RestApiGetCall& call) 128 static void GetStatistics(RestApiGetCall& call)
102 { 129 {
130 if (call.IsDocumentation())
131 {
132 call.GetDocumentation()
133 .SetTag("System")
134 .SetSummary("Get statistics")
135 .SetDescription("Get some statistics about Orthanc")
136 .SetAnswerField("CountInstances", RestApiCallDocumentation::Type_Number, "Number of DICOM instances stored in Orthanc")
137 .SetAnswerField("CountSeries", RestApiCallDocumentation::Type_Number, "Number of DICOM series stored in Orthanc")
138 .SetAnswerField("CountStudies", RestApiCallDocumentation::Type_Number, "Number of DICOM studies stored in Orthanc")
139 .SetAnswerField("CountPatients", RestApiCallDocumentation::Type_Number, "Number of patients stored in Orthanc")
140 .SetAnswerField("TotalDiskSize", RestApiCallDocumentation::Type_String, "Size of the storage area (in bytes)")
141 .SetAnswerField("TotalDiskSizeMB", RestApiCallDocumentation::Type_Number, "Size of the storage area (in megabytes)")
142 .SetAnswerField("TotalUncompressedSize", RestApiCallDocumentation::Type_String, "Total size of all the files once uncompressed (in bytes). This corresponds to \"TotalDiskSize\" if no compression is enabled, cf. \"StorageCompression\" configuration option")
143 .SetAnswerField("TotalUncompressedSizeMB", RestApiCallDocumentation::Type_Number, "Total size of all the files once uncompressed (in megabytes)")
144 .SetHttpGetSample("https://demo.orthanc-server.com/statistics", true);
145 return;
146 }
147
103 static const uint64_t MEGA_BYTES = 1024 * 1024; 148 static const uint64_t MEGA_BYTES = 1024 * 1024;
104 149
105 uint64_t diskSize, uncompressedSize, countPatients, countStudies, countSeries, countInstances; 150 uint64_t diskSize, uncompressedSize, countPatients, countStudies, countSeries, countInstances;
106 OrthancRestApi::GetIndex(call).GetGlobalStatistics(diskSize, uncompressedSize, countPatients, 151 OrthancRestApi::GetIndex(call).GetGlobalStatistics(diskSize, uncompressedSize, countPatients,
107 countStudies, countSeries, countInstances); 152 countStudies, countSeries, countInstances);
119 call.GetOutput().AnswerJson(result); 164 call.GetOutput().AnswerJson(result);
120 } 165 }
121 166
122 static void GenerateUid(RestApiGetCall& call) 167 static void GenerateUid(RestApiGetCall& call)
123 { 168 {
169 if (call.IsDocumentation())
170 {
171 call.GetDocumentation()
172 .SetTag("System")
173 .SetSummary("Generate an identifier")
174 .SetDescription("Generate a random DICOM identifier")
175 .SetHttpGetArgument("level", RestApiCallDocumentation::Type_String,
176 "Type of DICOM resource among: \"patient\", \"study\", \"series\" or \"instance\"")
177 .AddAnswerType(MimeType_PlainText, "The generated identifier");
178 return;
179 }
180
124 std::string level = call.GetArgument("level", ""); 181 std::string level = call.GetArgument("level", "");
125 if (level == "patient") 182 if (level == "patient")
126 { 183 {
127 call.GetOutput().AnswerBuffer(FromDcmtkBridge::GenerateUniqueIdentifier(ResourceType_Patient), MimeType_PlainText); 184 call.GetOutput().AnswerBuffer(FromDcmtkBridge::GenerateUniqueIdentifier(ResourceType_Patient), MimeType_PlainText);
128 } 185 }
140 } 197 }
141 } 198 }
142 199
143 static void ExecuteScript(RestApiPostCall& call) 200 static void ExecuteScript(RestApiPostCall& call)
144 { 201 {
202 if (call.IsDocumentation())
203 {
204 call.GetDocumentation()
205 .SetTag("System")
206 .SetSummary("Execute Lua script")
207 .SetDescription("Execute the provided Lua script by the Orthanc server. This is very insecure for "
208 "Orthanc servers that are remotely accessible, cf. configuration option \"ExecuteLuaEnabled\"")
209 .AddRequestType(MimeType_PlainText, "The Lua script to be executed")
210 .AddAnswerType(MimeType_PlainText, "Output of the Lua script");
211 return;
212 }
213
145 ServerContext& context = OrthancRestApi::GetContext(call); 214 ServerContext& context = OrthancRestApi::GetContext(call);
146 215
147 if (!context.IsExecuteLuaEnabled()) 216 if (!context.IsExecuteLuaEnabled())
148 { 217 {
149 LOG(ERROR) << "The URI /tools/execute-script is disallowed for security, " 218 LOG(ERROR) << "The URI /tools/execute-script is disallowed for security, "
165 } 234 }
166 235
167 template <bool UTC> 236 template <bool UTC>
168 static void GetNowIsoString(RestApiGetCall& call) 237 static void GetNowIsoString(RestApiGetCall& call)
169 { 238 {
239 if (call.IsDocumentation())
240 {
241 std::string type(UTC ? "UTC" : "local");
242 call.GetDocumentation()
243 .SetTag("System")
244 .SetSummary("Get " + type + " time")
245 .AddAnswerType(MimeType_PlainText, "The " + type + " time")
246 .SetHttpGetSample("https://demo.orthanc-server.com" + call.FlattenUri(), false);
247 return;
248 }
249
170 call.GetOutput().AnswerBuffer(SystemToolbox::GetNowIsoString(UTC), MimeType_PlainText); 250 call.GetOutput().AnswerBuffer(SystemToolbox::GetNowIsoString(UTC), MimeType_PlainText);
171 } 251 }
172 252
173 253
174 static void GetDicomConformanceStatement(RestApiGetCall& call) 254 static void GetDicomConformanceStatement(RestApiGetCall& call)
422 } 502 }
423 503
424 504
425 static void GetMetricsPrometheus(RestApiGetCall& call) 505 static void GetMetricsPrometheus(RestApiGetCall& call)
426 { 506 {
507 if (call.IsDocumentation())
508 {
509 call.GetDocumentation()
510 .SetTag("System")
511 .SetSummary("Get metrics")
512 .SetDescription("Get metrics in the Prometheus file format")
513 .SetHttpGetSample("https://demo.orthanc-server.com/tools/metrics-prometheus", false);
514 return;
515 }
516
427 #if ORTHANC_ENABLE_PLUGINS == 1 517 #if ORTHANC_ENABLE_PLUGINS == 1
428 OrthancRestApi::GetContext(call).GetPlugins().RefreshMetrics(); 518 OrthancRestApi::GetContext(call).GetPlugins().RefreshMetrics();
429 #endif 519 #endif
430 520
431 static const float MEGA_BYTES = 1024 * 1024; 521 static const float MEGA_BYTES = 1024 * 1024;
493 } 583 }
494 584
495 585
496 static void GetLogLevel(RestApiGetCall& call) 586 static void GetLogLevel(RestApiGetCall& call)
497 { 587 {
588 if (call.IsDocumentation())
589 {
590 call.GetDocumentation()
591 .SetTag("Logs")
592 .SetSummary("Get main log level")
593 .SetDescription("Get the main log level of Orthanc")
594 .AddAnswerType(MimeType_PlainText, "Possible values: \"default\", \"verbose\" or \"trace\"");
595 return;
596 }
597
498 const std::string s = EnumerationToString(GetGlobalVerbosity()); 598 const std::string s = EnumerationToString(GetGlobalVerbosity());
499 call.GetOutput().AnswerBuffer(s, MimeType_PlainText); 599 call.GetOutput().AnswerBuffer(s, MimeType_PlainText);
500 } 600 }
501 601
502 602
503 static void PutLogLevel(RestApiPutCall& call) 603 static void PutLogLevel(RestApiPutCall& call)
504 { 604 {
605 if (call.IsDocumentation())
606 {
607 call.GetDocumentation()
608 .SetTag("Logs")
609 .SetSummary("Set main log level")
610 .SetDescription("Set the main log level of Orthanc")
611 .AddRequestType(MimeType_PlainText, "Possible values: \"default\", \"verbose\" or \"trace\"");
612 return;
613 }
614
505 std::string body; 615 std::string body;
506 call.BodyToString(body); 616 call.BodyToString(body);
507 617
508 SetGlobalVerbosity(StringToVerbosity(body)); 618 SetGlobalVerbosity(StringToVerbosity(body));
509 619
532 } 642 }
533 643
534 644
535 static void GetLogLevelCategory(RestApiGetCall& call) 645 static void GetLogLevelCategory(RestApiGetCall& call)
536 { 646 {
647 if (call.IsDocumentation())
648 {
649 std::string category = Logging::GetCategoryName(GetCategory(call));
650 call.GetDocumentation()
651 .SetTag("Logs")
652 .SetSummary("Get log level for \"" + category + "\"")
653 .SetDescription("Get the log level of the log category \"" + category + "\"")
654 .AddAnswerType(MimeType_PlainText, "Possible values: \"default\", \"verbose\" or \"trace\"");
655 return;
656 }
657
537 const std::string s = EnumerationToString(GetCategoryVerbosity(GetCategory(call))); 658 const std::string s = EnumerationToString(GetCategoryVerbosity(GetCategory(call)));
538 call.GetOutput().AnswerBuffer(s, MimeType_PlainText); 659 call.GetOutput().AnswerBuffer(s, MimeType_PlainText);
539 } 660 }
540 661
541 662
542 static void PutLogLevelCategory(RestApiPutCall& call) 663 static void PutLogLevelCategory(RestApiPutCall& call)
543 { 664 {
665 if (call.IsDocumentation())
666 {
667 std::string category = Logging::GetCategoryName(GetCategory(call));
668 call.GetDocumentation()
669 .SetTag("Logs")
670 .SetSummary("Set log level for \"" + category + "\"")
671 .SetDescription("Set the log level of the log category \"" + category + "\"")
672 .AddRequestType(MimeType_PlainText, "Possible values: \"default\", \"verbose\" or \"trace\"");
673 return;
674 }
675
544 std::string body; 676 std::string body;
545 call.BodyToString(body); 677 call.BodyToString(body);
546 678
547 Verbosity verbosity = StringToVerbosity(body); 679 Verbosity verbosity = StringToVerbosity(body);
548 Logging::LogCategory category = GetCategory(call); 680 Logging::LogCategory category = GetCategory(call);