Mercurial > hg > orthanc-book
annotate Sphinx/source/users/rest.rst @ 114:736d30badda0
large POST body
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Thu, 20 Jul 2017 17:22:13 +0200 |
| parents | 5737f51ff94e |
| children | 55a2ee3c462d |
| rev | line source |
|---|---|
| 0 | 1 .. _rest: |
| 2 | |
| 3 REST API of Orthanc | |
| 4 =================== | |
| 5 | |
| 6 .. contents:: | |
| 7 :depth: 3 | |
| 8 | |
| 9 One of the major strengths of Orthanc lies in its built-in `RESTful | |
| 10 API | |
| 11 <https://en.wikipedia.org/wiki/Representational_state_transfer>`__, | |
| 12 that can be used to drive Orthanc from external applications, | |
| 13 independently of the programming language that is used to develop | |
| 14 these applications. The REST API of Orthanc gives a full programmatic | |
| 15 access to all the core features of Orthanc. | |
| 16 | |
| 17 Importantly, Orthanc Explorer (the embedded administrative interface | |
| 18 of Orthanc) entirely resorts to this REST API for all its features. | |
| 19 This implies that anything that can be done through Orthanc Explorer, | |
| 20 can also be done through REST queries. | |
| 21 | |
| 22 *Note:* All the examples are illustrated with the `cURL command-line | |
| 25 | 23 tool <https://curl.haxx.se/>`__, but equivalent calls can be readily |
| 0 | 24 transposed to any programming language that supports both HTTP and |
| 25 JSON. | |
| 26 | |
| 27 | |
| 114 | 28 .. _sending-dicom-images: |
| 29 | |
| 0 | 30 Sending DICOM images |
| 31 -------------------- | |
| 32 | |
| 33 .. highlight:: bash | |
| 34 | |
| 35 The upload of DICOM files is possible by querying the REST API using | |
| 36 the following syntax:: | |
| 37 | |
| 38 $ curl -X POST http://localhost:8042/instances --data-binary @CT.X.1.2.276.0.7230010.dcm | |
| 39 | |
| 40 .. highlight:: json | |
| 41 | |
| 42 Orthanc will respond with a JSON file that contain information about | |
| 43 the location of the stored instance, such as:: | |
| 44 | |
| 45 { | |
| 46 "ID" : "e87da270-c52b-4f2a-b8c6-bae25928d0b0", | |
| 47 "Path" : "/instances/e87da270-c52b-4f2a-b8c6-bae25928d0b0", | |
| 48 "Status" : "Success" | |
| 49 } | |
| 50 | |
| 51 .. highlight:: bash | |
| 52 | |
| 53 Note that in the case of curl, setting the ``Expect`` HTTP Header will | |
| 54 significantly `reduce the execution time of POST requests | |
| 25 | 55 <http://stackoverflow.com/questions/463144/php-http-post-fails-when-curl-data-1024/463277#463277>`__:: |
| 0 | 56 |
| 57 $ curl -X POST -H "Expect:" http://localhost:8042/instances --data-binary @CT.X.1.2.276.0.7230010.dcm | |
| 58 | |
| 59 The code distribution of Orthanc contains a `sample Python script | |
| 60 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/ImportDicomFiles/ImportDicomFiles.py>`__ | |
| 61 that recursively upload the content of some folder into Orthanc using | |
| 62 the REST API:: | |
| 63 | |
| 64 $ python ImportDicomFiles.py localhost 8042 ~/DICOM/ | |
| 65 | |
| 66 | |
| 67 .. _rest-access: | |
| 68 | |
| 69 Accessing the content of Orthanc | |
| 70 -------------------------------- | |
| 71 | |
| 72 Orthanc structures the stored DICOM resources using the "Patient, | |
| 73 Study, Series, Instance" model of the DICOM standard. Each DICOM | |
| 74 resource is associated with an :ref:`unique identifier <orthanc-ids>`. | |
| 75 | |
| 76 List all the DICOM resources | |
| 77 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 78 | |
| 79 Here is how you would list all the DICOM resources that are stored in | |
| 80 your local Orthanc instance:: | |
| 81 | |
| 82 $ curl http://localhost:8042/patients | |
| 83 $ curl http://localhost:8042/studies | |
| 84 $ curl http://localhost:8042/series | |
| 85 $ curl http://localhost:8042/instances | |
| 86 | |
| 87 Note that the result of this command is a `JSON file | |
| 25 | 88 <https://en.wikipedia.org/wiki/Json>`__ that contains an array of |
| 0 | 89 resource identifiers. The JSON file format is lightweight and can be |
| 90 parsed from almost any computer language. | |
| 91 | |
| 92 Accessing a patient | |
| 93 ^^^^^^^^^^^^^^^^^^^ | |
| 94 | |
| 95 .. highlight:: bash | |
| 96 | |
| 97 To access a single resource, add its identifier to the `URI | |
| 25 | 98 <https://en.wikipedia.org/wiki/Uniform_resource_identifier>`__. You |
| 0 | 99 would for instance retrieve the main information about one patient as |
| 100 follows:: | |
| 101 | |
| 102 $ curl http://localhost:8042/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94 | |
| 103 | |
| 104 .. highlight:: json | |
| 105 | |
| 106 Here is a possible answer from Orthanc:: | |
| 107 | |
| 108 { | |
| 109 "ID" : "07a6ec1c-1be5920b-18ef5358-d24441f3-10e926ea", | |
| 110 "MainDicomTags" : { | |
| 111 "OtherPatientIDs" : "(null)", | |
| 112 "PatientBirthDate" : "0", | |
| 113 "PatientID" : "000000185", | |
| 114 "PatientName" : "Anonymous^Unknown", | |
| 115 "PatientSex" : "O" | |
| 116 }, | |
| 117 "Studies" : [ "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15" ], | |
| 118 "Type" : "Patient" | |
| 119 } | |
| 120 | |
| 121 This is once again a JSON file. Note how Orthanc gives you a summary | |
| 122 of the main DICOM tags that correspond to the patient level. | |
| 123 | |
| 124 Browsing from the patient down to the instance | |
| 125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 126 | |
| 127 .. highlight:: bash | |
| 128 | |
| 129 The field ``Studies`` list all the DICOM studies that are associated | |
| 130 with the patient. So, considering the patient above, we would go down | |
| 131 in her DICOM hierarchy as follows:: | |
| 132 | |
| 133 $ curl http://localhost:8042/studies/9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15 | |
| 134 | |
| 135 .. highlight:: json | |
| 136 | |
| 137 And Orthanc could answer:: | |
| 138 | |
| 139 { | |
| 140 "ID" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15", | |
| 141 "MainDicomTags" : { | |
| 142 "AccessionNumber" : "(null)", | |
| 143 "StudyDate" : "20120716", | |
| 144 "StudyDescription" : "TestSUVce-TF", | |
| 145 "StudyID" : "23848", | |
| 146 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40", | |
| 147 "StudyTime" : "170728" | |
| 148 }, | |
| 149 "ParentPatient" : "07a6ec1c-1be5920b-18ef5358-d24441f3-10e926ea", | |
| 150 "Series" : [ | |
| 151 "6821d761-31fb55a9-031ebecb-ba7f9aae-ffe4ddc0", | |
| 152 "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 153 "7384c47e-6398f2a8-901846ef-da1e2e0b-6c50d598" | |
| 154 ], | |
| 155 "Type" : "Study" | |
| 156 } | |
| 157 | |
| 158 .. highlight:: bash | |
| 159 | |
| 160 The main DICOM tags are now those that are related to the study | |
| 161 level. It is possible to retrieve the identifier of the patient in the | |
| 162 ``ParentPatient`` field, which can be used to go upward the DICOM | |
| 163 hierarchy. But let us rather go down to the series level by using the | |
| 164 ``Series`` array. The next command would return information about one | |
| 165 of the three series that have just been reported:: | |
| 166 | |
| 167 $ curl http://localhost:8042/series/2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35 | |
| 168 | |
| 169 .. highlight:: json | |
| 170 | |
| 171 Here is a possible answer:: | |
| 172 | |
| 173 { | |
| 174 "ExpectedNumberOfInstances" : 45, | |
| 175 "ID" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 176 "Instances" : [ | |
| 177 "41bc3f74-360f9d10-6ae9ffa4-01ea2045-cbd457dd", | |
| 178 "1d3de868-6c4f0494-709fd140-7ccc4c94-a6daa3a8", | |
| 179 <...> | |
| 180 "1010f80b-161b71c0-897ec01b-c85cd206-e669a3ea", | |
| 181 "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4" | |
| 182 ], | |
| 183 "MainDicomTags" : { | |
| 184 "Manufacturer" : "Philips Medical Systems", | |
| 185 "Modality" : "PT", | |
| 186 "NumberOfSlices" : "45", | |
| 187 "ProtocolName" : "CHU/Body_PET/CT___50", | |
| 188 "SeriesDate" : "20120716", | |
| 189 "SeriesDescription" : "[WB_CTAC] Body", | |
| 190 "SeriesInstanceUID" : "1.3.46.670589.28.2.12.30.26407.37145.2.2516.0.1342458737", | |
| 191 "SeriesNumber" : "587370", | |
| 192 "SeriesTime" : "171121", | |
| 193 "StationName" : "r054-svr" | |
| 194 }, | |
| 195 "ParentStudy" : "9ad2b0da-a406c43c-6e0df76d-1204b86f-78d12c15", | |
| 196 "Status" : "Complete", | |
| 197 "Type" : "Series" | |
| 198 } | |
| 199 | |
| 200 It can be seen that this series comes from a PET modality. Orthanc has | |
| 201 computed that this series should contain 45 instances. | |
| 202 | |
| 203 .. highlight:: bash | |
| 204 | |
| 205 So far, we have navigated from the patient level, to the study level, | |
| 206 and finally to the series level. There only remains the instance | |
| 207 level. Let us dump the content of one of the instances:: | |
| 208 | |
| 209 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4 | |
| 210 | |
| 211 .. highlight:: json | |
| 212 | |
| 213 The instance contains the following information:: | |
| 214 | |
| 215 { | |
| 216 "FileSize" : 70356, | |
| 217 "FileUuid" : "3fd265f0-c2b6-41a2-ace8-ae332db63e06", | |
| 218 "ID" : "e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4", | |
| 219 "IndexInSeries" : 6, | |
| 220 "MainDicomTags" : { | |
| 221 "ImageIndex" : "6", | |
| 222 "InstanceCreationDate" : "20120716", | |
| 223 "InstanceCreationTime" : "171344", | |
| 224 "InstanceNumber" : "6", | |
| 225 "SOPInstanceUID" : "1.3.46.670589.28.2.15.30.26407.37145.3.2116.39.1342458737" | |
| 226 }, | |
| 227 "ParentSeries" : "2cc6336f-2d4ae733-537b3ca3-e98184b1-ba494b35", | |
| 228 "Type" : "Instance" | |
| 229 } | |
| 230 | |
| 231 .. highlight:: bash | |
| 232 | |
| 233 The instance has the index 6 in the parent series. The instance is | |
| 234 stored as a raw DICOM file of 70356 bytes. You would download this | |
| 235 DICOM file using the following command:: | |
| 236 | |
| 237 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/file > Instance.dcm | |
| 238 | |
| 239 | |
| 240 Accessing the DICOM fields of an instance as a JSON file | |
| 241 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 242 | |
| 243 .. highlight:: bash | |
| 244 | |
| 245 When one gets to the instance level, you can retrieve the hierarchy of | |
| 246 all the DICOM tags of this instance as a JSON file:: | |
| 247 | |
| 248 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/simplified-tags | |
| 249 | |
| 250 .. highlight:: json | |
| 251 | |
| 252 Here is a excerpt of the Orthanc answer:: | |
| 253 | |
| 254 { | |
| 255 "ACR_NEMA_2C_VariablePixelDataGroupLength" : "57130", | |
| 256 "AccessionNumber" : null, | |
| 257 "AcquisitionDate" : "20120716", | |
| 258 "AcquisitionDateTime" : "20120716171219", | |
| 259 "AcquisitionTime" : "171219", | |
| 260 "ActualFrameDuration" : "3597793", | |
| 261 "AttenuationCorrectionMethod" : "CTAC-SG", | |
| 262 <...> | |
| 263 "PatientID" : "000000185", | |
| 264 "PatientName" : "Anonymous^Unknown", | |
| 265 "PatientOrientationCodeSequence" : [ | |
| 266 { | |
| 267 "CodeMeaning" : "recumbent", | |
| 268 "CodeValue" : "F-10450", | |
| 269 "CodingSchemeDesignator" : "99SDM", | |
| 270 "PatientOrientationModifierCodeSequence" : [ | |
| 271 { | |
| 272 "CodeMeaning" : "supine", | |
| 273 "CodeValue" : "F-10340", | |
| 274 "CodingSchemeDesignator" : "99SDM" | |
| 275 } | |
| 276 ] | |
| 277 } | |
| 278 ], | |
| 279 <...> | |
| 280 "StudyDescription" : "TestSUVce-TF", | |
| 281 "StudyID" : "23848", | |
| 282 "StudyInstanceUID" : "1.2.840.113704.1.111.7016.1342451220.40", | |
| 283 "StudyTime" : "171117", | |
| 284 "TypeOfDetectorMotion" : "NONE", | |
| 285 "Units" : "BQML", | |
| 286 "Unknown" : null, | |
| 287 "WindowCenter" : "1.496995e+04", | |
| 288 "WindowWidth" : "2.993990e+04" | |
| 289 } | |
| 290 | |
| 291 .. highlight:: bash | |
| 292 | |
| 293 If you need more detailed information about the type of the variables | |
| 294 or if you wish to use the hexadecimal indexes of DICOM tags, you are | |
| 295 free to use the following URL:: | |
| 296 | |
| 297 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/tags | |
| 298 | |
| 299 Accessing the raw DICOM fields of an instance | |
| 300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 301 | |
| 302 .. highlight:: bash | |
| 303 | |
| 304 You also have the opportunity to access the raw value of the DICOM | |
| 305 tags of an instance, without going through a JSON file. Here is how | |
| 306 you would find the Patient Name of the instance:: | |
| 307 | |
| 308 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content/0010-0010 | |
| 309 Anonymous^Unknown | |
| 310 | |
| 311 The list of all the available tags for this instance can also be retrieved easily:: | |
| 312 | |
| 313 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content | |
| 314 | |
| 315 It is also possible to recursively explore the sequences of tags:: | |
| 316 | |
| 317 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/content/0008-1250/0/0040-a170/0/0008-0104 | |
| 318 For Attenuation Correction | |
| 319 | |
| 320 The command above has opened the "0008-1250" tag that is a DICOM | |
| 321 sequence, taken its first child, opened its "0040-a170" tag that is | |
| 322 also a sequence, taken the first child of this child, and returned the | |
| 323 "0008-0104" DICOM tag. | |
| 324 | |
| 325 Downloading images | |
| 326 ^^^^^^^^^^^^^^^^^^ | |
| 327 | |
| 328 .. highlight:: bash | |
| 329 | |
| 330 It is also possible to download a preview PNG image that corresponds to some DICOM instance:: | |
| 331 | |
| 332 $ curl http://localhost:8042/instances/e668dcbf-8829a100-c0bd203b-41e404d9-c533f3d4/preview > Preview.png | |
| 333 | |
| 334 The resulting image will be a standard graylevel PNG image that can be opened by any painting software. | |
| 335 | |
| 336 | |
| 337 .. _changes: | |
| 338 | |
| 339 | |
| 340 | |
| 341 Sending resources to remote modalities | |
| 342 -------------------------------------- | |
| 343 | |
| 344 Orthanc can send its DICOM instances to remote DICOM modalities (C-Store SCU). This process | |
| 345 can be triggered by the REST API. | |
| 346 | |
| 347 Configuration | |
| 348 ^^^^^^^^^^^^^ | |
| 349 | |
| 350 .. highlight:: json | |
| 351 | |
| 352 You first have to declare the AET, the IP address and the port number | |
| 353 of the remote modality inside the :ref:`configuration file | |
| 354 <configuration>`. For instance, here is how to declare a remote | |
| 355 modality:: | |
| 356 | |
| 357 ... | |
| 358 "DicomModalities" : { | |
| 359 "sample" : [ "STORESCP", "127.0.0.1", 2000 ] | |
| 360 }, | |
| 361 ... | |
| 362 | |
| 363 .. highlight:: bash | |
| 364 | |
| 365 Such a configuration would enable Orthanc to connect to another DICOM | |
| 366 store (for instance, another Orthanc instance) that listens on the | |
| 367 localhost on the port 2000. The modalities that are known to Orthanc | |
| 368 can be queried:: | |
| 369 | |
| 370 $ curl http://localhost:8042/modalities | |
| 371 | |
| 372 | |
| 373 Sending One Resource | |
| 374 ^^^^^^^^^^^^^^^^^^^^ | |
| 375 | |
| 376 .. highlight:: bash | |
| 377 | |
| 378 Once you have identified the Orthanc identifier of the DICOM resource | |
| 379 that would like to send :ref:`as explained above <rest-access>`, you | |
| 380 would use the following command to send it:: | |
| 381 | |
| 382 $ curl -X POST http://localhost:8042/modalities/sample/store -d c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f | |
| 383 | |
| 384 The ``/sample/`` component of the URI corresponds to the identifier of | |
| 385 the remote modality, as specified above in the configuration file. | |
| 386 | |
| 387 Note that you can send isolated DICOM instances with this command, but also entire patients, studies or series. | |
| 388 | |
| 389 Bulk Store SCU | |
| 390 ^^^^^^^^^^^^^^ | |
| 391 | |
| 392 .. highlight:: bash | |
| 393 | |
| 394 Each time a POST request is made to ``/modalities/.../store``, a new | |
| 395 DICOM connection is possibly established. This may lead to a large | |
| 396 communication overhead if sending multiple isolated instances. | |
| 397 | |
| 398 To circumvent this problem, you have 2 possibilities: | |
| 399 | |
| 400 1. Set the ``DicomAssociationCloseDelay`` option in the | |
| 401 :ref:`configuration file <configuration>` to a non-zero value. This | |
| 402 will keep the DICOM connection open for a certain amount of time, | |
| 403 waiting for new instances to be routed. | |
| 404 | |
| 405 2. If you do not want to keep the connection open but inactive, it is | |
| 406 possible to send multiple instances with a single POST request | |
| 407 (so-called "Bulk Store SCU", available from Orthanc 0.5.2):: | |
| 408 | |
| 409 $ curl -X POST http://localhost:8042/modalities/sample/store -d '["d4b46c8e-74b16992-b0f5ca11-f04a60fa-8eb13a88","d5604121-7d613ce6-c315a5-a77b3cf3-9c253b23","cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e"]' | |
| 410 | |
| 411 The list of the resources to be sent are given as a JSON array. In | |
| 412 this case, a single DICOM connection is used. `Sample code is | |
| 413 available | |
| 414 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/HighPerformanceAutoRouting.py>`__. | |
| 415 | |
| 416 | |
| 417 Tracking changes | |
| 418 ---------------- | |
| 419 | |
| 420 .. highlight:: bash | |
| 421 | |
| 422 Whenever Orthanc receives a new DICOM instance, this event is recorded | |
| 423 in the so-called "Changes Log". This enables remote scripts to react | |
| 424 to the arrival of new DICOM resources. A typical application is | |
| 425 **auto-routing**, where an external script waits for a new DICOM | |
| 426 instance to arrive into Orthanc, then forward this instance to another | |
| 427 modality. | |
| 428 | |
| 429 The Changes Log can be accessed by the following command:: | |
| 430 | |
| 431 $ curl http://localhost:8042/changes | |
| 432 | |
| 433 .. highlight:: json | |
| 434 | |
| 435 Here is a typical output:: | |
| 436 | |
| 437 { | |
| 438 "Changes" : [ | |
| 439 { | |
| 440 "ChangeType" : "NewInstance", | |
| 441 "Date" : "20130507T143902", | |
| 442 "ID" : "8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe", | |
| 443 "Path" : "/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe", | |
| 444 "ResourceType" : "Instance", | |
| 445 "Seq" : 921 | |
| 446 }, | |
| 447 { | |
| 448 "ChangeType" : "NewSeries", | |
| 449 "Date" : "20130507T143902", | |
| 450 "ID" : "cceb768f-e0f8df71-511b0277-07e55743-9ef8890d", | |
| 451 "Path" : "/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d", | |
| 452 "ResourceType" : "Series", | |
| 453 "Seq" : 922 | |
| 454 }, | |
| 455 { | |
| 456 "ChangeType" : "NewStudy", | |
| 457 "Date" : "20130507T143902", | |
| 458 "ID" : "c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f", | |
| 459 "Path" : "/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f", | |
| 460 "ResourceType" : "Study", | |
| 461 "Seq" : 923 | |
| 462 }, | |
| 463 { | |
| 464 "ChangeType" : "NewPatient", | |
| 465 "Date" : "20130507T143902", | |
| 466 "ID" : "dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94", | |
| 467 "Path" : "/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94", | |
| 468 "ResourceType" : "Patient", | |
| 469 "Seq" : 924 | |
| 470 } | |
| 471 ], | |
| 472 "Done" : true, | |
| 473 "Last" : 924 | |
| 474 } | |
| 475 | |
| 476 This output corresponds to the receiving of one single DICOM instance | |
| 477 by Orthanc. It records that a new instance, a new series, a new study | |
| 478 and a new patient has been created inside Orthanc. Note that each | |
| 479 changes is labeled by a ``ChangeType``, a ``Date`` (in the `ISO format | |
| 25 | 480 <https://en.wikipedia.org/wiki/ISO_8601>`__), the location of the |
| 0 | 481 resource inside Orthanc, and a sequence number (``Seq``). |
| 482 | |
| 483 Note that this call is non-blocking. It is up to the calling program | |
| 484 to wait for the occurrence of a new event (by implementing a polling | |
| 485 loop). | |
| 486 | |
| 487 .. highlight:: bash | |
| 488 | |
| 489 This call only returns a fixed number of events, that can be changed | |
| 490 by using the ``limit`` option:: | |
| 491 | |
| 492 $ curl http://localhost:8042/changes?limit=100 | |
| 493 | |
| 494 The flag ``Last`` records the sequence number of the lastly returned | |
| 495 event. The flag ``Done`` is set to ``true`` if no further event has | |
| 496 occurred after this lastly returned event. If ``Done`` is set to | |
| 497 ``false``, further events are available and can be retrieved. This is | |
| 498 done by setting the ``since`` option that specifies from which | |
| 499 sequence number the changes must be returned:: | |
| 500 | |
| 501 $ curl 'http://localhost:8042/changes?limit=100&since=922' | |
| 502 | |
| 503 A `sample code in the source distribution | |
| 504 <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/ChangesLoop.py>`__ | |
| 505 shows how to use this Changes API to implement a polling loop. | |
| 506 | |
| 507 | |
| 508 Deleting resources from Orthanc | |
| 509 ------------------------------- | |
| 510 | |
| 511 .. highlight:: bash | |
| 512 | |
| 513 Deleting patients, studies, series or instances | |
| 514 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 515 | |
| 516 Deleting DICOM resources (i.e. patients, studies, series or instances) | |
| 517 from Orthanc is as simple as using a HTTP DELETE on the URI of this | |
| 518 resource. | |
| 519 | |
| 520 Concretely, you would first explore the resources that are stored in | |
| 521 Orthanc :ref:`as explained above <rest-access>`:: | |
| 522 | |
| 523 $ curl http://localhost:8042/patients | |
| 524 $ curl http://localhost:8042/studies | |
| 525 $ curl http://localhost:8042/series | |
| 526 $ curl http://localhost:8042/instances | |
| 527 | |
| 528 Secondly, once you have spotted the resources to be removed, you would | |
| 529 use the following command-line syntax to delete them:: | |
| 530 | |
| 531 $ curl -X DELETE http://localhost:8042/patients/dc65762c-f476e8b9-898834f4-2f8a5014-2599bc94 | |
| 532 $ curl -X DELETE http://localhost:8042/studies/c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f | |
| 533 $ curl -X DELETE http://localhost:8042/series/cceb768f-e0f8df71-511b0277-07e55743-9ef8890d | |
| 534 $ curl -X DELETE http://localhost:8042/instances/8e289db9-0e1437e1-3ecf395f-d8aae463-f4bb49fe | |
| 535 | |
| 536 | |
| 537 Clearing log of changes | |
| 538 ^^^^^^^^^^^^^^^^^^^^^^^ | |
| 539 | |
| 540 :ref:`As described above <changes>`, Orthanc keeps track of all the | |
| 541 changes that occur in the DICOM store. This so-called "Changes Log" | |
| 542 is accessible at the following URI:: | |
| 543 | |
| 544 $ curl http://localhost:8042/changes | |
| 545 | |
| 546 To clear the content of the Changes Log, simply DELETE this URI:: | |
| 547 | |
| 548 $ curl -X DELETE http://localhost:8042/changes | |
| 549 | |
| 550 Clearing log of exported resources | |
| 551 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 552 | |
| 553 For medical traceability, Orthanc stores a log of all the resources | |
| 554 that have been exported to remote modalities:: | |
| 555 | |
| 556 $ curl http://localhost:8042/exports | |
| 557 | |
| 558 In auto-routing scenarios, it is important to prevent this log to grow | |
| 559 indefinitely as incoming instances are routed. You can either disable | |
| 560 this logging by setting the option ``LogExportedResources`` to ``false`` | |
| 561 in the :ref:`configuration file <configuration>`, or periodically | |
| 562 clear this log by DELETE-ing this URI:: | |
| 563 | |
| 564 $ curl -X DELETE http://localhost:8042/exports | |
| 565 | |
| 566 | |
| 567 Anonymization and modification | |
| 568 ------------------------------ | |
| 569 | |
| 570 The process of anonymizing and modifying DICOM resources is | |
| 571 :ref:`documented in a separate page <anonymization>`. | |
| 572 | |
| 573 | |
| 574 Further reading | |
| 575 --------------- | |
| 576 | |
| 577 The examples above have shown you the basic principles for driving an | |
| 578 instance of Orthanc through its REST API. All the possibilities of the | |
|
35
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
579 API have not been described: |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
580 |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
581 * A :ref:`FAQ entry <rest-samples>` lists where you can find more |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
582 advanced samples of the REST API of Orthanc. |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
583 * The full documentation of the REST API is maintained as an online |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
584 spreadsheet accessible from the `documentation part of the official |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
585 Web site |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
586 <http://www.orthanc-server.com/static.php?page=documentation>`__ |
|
5737f51ff94e
How does Orthanc stores its database
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
25
diff
changeset
|
587 (click on the *Reference of the REST API* button). |