Mercurial > hg > orthanc-book

comparison Sphinx/source/users/advanced-rest.rst @ 224:02399e86f046

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
starting documentation of jobs
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 06 Mar 2019 07:41:49 +0100
parents
children ced9dbf86de8
comparison
equal deleted inserted replaced
223:9ccafca945d2 224:02399e86f046
1 .. _rest-advanced:
2
3 Advanced features of the REST API
4 =================================
5
6 .. contents::
7 :depth: 3
8
9 This section of the Orthanc Book is a complement to the description of
10 the :ref:`REST API of Orthanc <rest>`. It explains some advanced uses
11 of the API.
12
13
14 .. _jobs:
15
16 Jobs
17 ----
18
19 Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs
20 are tasks to be done by Orthanc. Jobs are first added to a queue of
21 pending tasks, and Orthanc will simultaneously a fixed number of jobs
22 (check out :ref:`configuration option <configuration>`
23 ``ConcurrentJobs``). Once the jobs have been processed, they are tagged
24 as successful or failed, and kept in a history (the size of this
25 history is controlled by the ``JobsHistorySize`` option).
26
27 Synchronous vs. asynchronous
28 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
29
30 Some calls to the REST API of Orthanc require time to be executed, and
31 thus result in adding a job to the processing queue. This notably
32 includes the following URIs:
33
34 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances.
35 * Creating ZIP or media archives.
36 * C-Move SCU (``/queries/.../retrieve``).
37 * C-Store SCU (``/modalities/.../store``).
38 * Sending to an Orthanc peer (``/peers/.../store``).
39 * :ref:`Split/merge <split-merge>`.
40 * Sending images using the :ref:`transfers accelerator <transfers>` plugin.
41
42 Such REST API calls can be configured to be executed in a synchronous
43 or an asynchronous mode:
44
45 * **Synchronous calls** wait for the end of the execution of their
46 associated job. This is in general the default behavior.
47 * **Asynchronous calls** end immediately and return a handle to their
48 associated job. It is up to the caller to monitor the end of the
49 execution by calling the jobs API.
50
51 The choice between synchronous and asynchronous modes is done by
52 setting the `Synchronous` field (or indifferently `Asynchronous`
53 field) in the POST body of the call to the REST API. Note that the
54 :ref:`transfers accelerator <transfers>` only run in the asynchronous
55 mode.
56
57 Even if it is more complex to handle, the asynchronous mode is highly
58 recommended for jobs whose execution time can last over a dozen of
59 seconds (typically, the creation of an archive or a network transfer).
60 Indeed, this prevents timeouts in the HTTP protocol.
61
62
63
64
65 .. _pdf:
66
67 PDF
68 ---
69
70 TODO