Mercurial > hg > orthanc-book

comparison Sphinx/source/users/rest.rst @ 216:dcf6c2e60448

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added section about peering (wip)
author amazy
date Mon, 25 Feb 2019 18:56:30 +0100
parents 7ff807cc5ade
children 8bb11cd0f20f
comparison
equal deleted inserted replaced
214:f8c55b461d16 216:dcf6c2e60448
367 $ curl -H 'Accept: image/x-portable-arbitrarymap' http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/image-uint16 > full-16.pam 367 $ curl -H 'Accept: image/x-portable-arbitrarymap' http://localhost:8042/instances/609665c0-c5198aa2-8632476b-a00e0de0-e9075d94/image-uint16 > full-16.pam
368 368
369 Users of Matlab or Octave can find related information :ref:`in the 369 Users of Matlab or Octave can find related information :ref:`in the
370 dedicated section <matlab>`. 370 dedicated section <matlab>`.
371 371
372 372 Sending resources to remote Orthanc over HTTP/HTTPS (through Orthanc peering)
373 .. _changes: 373 ------------------------------------------------------
374 374
375 Sending resources to remote modalities 375 Orthanc can send its DICOM instances to remote Orthanc over HTTP/HTTPS through its Rest API.
376 -------------------------------------- 376 This process can be triggered by the REST API.
377
378 Configuration
379 ^^^^^^^^^^^^^
380
381 .. highlight:: json
382
383 You first have to declare the Url of the remote orthanc inside the :ref:`configuration file
384 <configuration>`. For instance, here is how to declare a remote
385 orthanc peer::
386
387 ...
388 "Peers" : {
389 "sample" : [ "http://localhost:8043" ], // short version
390 "sample2" : { // long version
391 "Url" : "http://localhost:8044",
392 "Username" : "alice", // optional
393 "Password" : "alicePassword", // optional
394 "HttpHeaders" : { "Token" : "Hello world" }, // optional
395 "CertificateFile" : "client.crt", // optional (only if using client certificate authentication)
396 "CertificateKeyFile" : "client.key", // optional (only if using client certificate authentication)
397 "CertificateKeyPassword" : "certpass" // optional (only if using client certificate authentication)
398 },
399 ...
400
401 .. highlight:: bash
402
403 Such a configuration would enable Orthanc to connect to two other
404 Orthanc instances that listens on the
405 localhost on the port 8043 & 8044. The peers that are known to Orthanc
406 can be queried::
407
408 $ curl http://localhost:8042/peers?expand
409
410 The peers can then be updated through the API too::
411
412 $ curl -v -X PUT http://localhost:8042/peers/sample -d '{"Url" : "http://127.0.0.1:8043"}'
413
414
415 Note that, by default, peers are stored in Orthanc configuration files
416 and are updated in Orthanc memory only. If you want your modifications
417 to be persistent, you should configure Orthanc to store its peers
418 in the database. This is done through this configuration::
419
420 ...
421 "OrthancPeersInDatabase" : true,
422 ...
423
424 Sending One Resource
425 ^^^^^^^^^^^^^^^^^^^^
426
427 .. highlight:: bash
428
429 Once you have identified the Orthanc identifier of the DICOM resource
430 that would like to send :ref:`as explained above <rest-access>`, you
431 would use the following command to send it::
432
433 $ curl -X POST http://localhost:8042/peers/sample/store -d c4ec7f68-9b162055-2c8c5888-5bf5752f-155ab19f
434
435 The ``/sample/`` component of the URI corresponds to the identifier of
436 the remote modality, as specified above in the configuration file.
437
438 Note that you can send isolated DICOM instances with this command, but
439 also entire patients, studies or series. It is possible to send multiple instances with a single POST
440 request::
441
442 $ curl -X POST http://localhost:8042/peers/sample/store -d '["d4b46c8e-74b16992-b0f5ca11-f04a60fa-8eb13a88","d5604121-7d613ce6-c315a5-a77b3cf3-9c253b23","cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e"]'
443
444 Note that the list of resources to be sent can include the
445 :ref:`Orthanc identifiers <orthanc-ids>` of entire patients,
446 studies or series as well.
447
448 Using HTTPS
449 ^^^^^^^^^^^
450
451 If you're transfering medical data over internet, it is mandatory to use HTTPS.
452
453 On the server side, we recommend to put Orthanc behing an :ref:`HTTPS server that will take care of the TLS <https>`.
454
455 On the client side, in order for the client Orthanc to recognize the server certificate, you'll have to provide a path
456 to the CA (certification authority) certificates. This is done in the configuration file through this configurationg::
457
458 ...
459 "HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt,
460 ...
461
462 If you wan't your server to accept incoming connections for known hosts only, you can either:
463
464 - configure a firewall to accept incoming connections from known IP addresses
465 - configure your client Orthanc to use a client certificate to authenticate at the Server. This is done through the ``CertificateFile``, ``CertificateKeyFile`` and ``CertificateKeyPassword`` entries in the configuration file.
466
467
468
469
470 Sending resources to remote modalities (through DICOM)
471 ------------------------------------------------------
377 472
378 Orthanc can send its DICOM instances to remote DICOM modalities (C-Store SCU). This process 473 Orthanc can send its DICOM instances to remote DICOM modalities (C-Store SCU). This process
379 can be triggered by the REST API. 474 can be triggered by the REST API.
380 475
381 Configuration 476 Configuration
656 751
657 You also have the ability to limit the responses by specifying a limit within the body of the POST message. For example:: 752 You also have the ability to limit the responses by specifying a limit within the body of the POST message. For example::
658 753
659 "Limit":4 754 "Limit":4
660 755
756
757 .. _changes:
661 758
662 Tracking changes 759 Tracking changes
663 ---------------- 760 ----------------
664 761
665 .. highlight:: bash 762 .. highlight:: bash