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