--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/users/advanced-rest.rst	Wed Mar 06 07:41:49 2019 +0100
@@ -0,0 +1,70 @@
+.. _rest-advanced:
+
+Advanced features of the REST API
+=================================
+
+.. contents::
+   :depth: 3
+
+This section of the Orthanc Book is a complement to the description of
+the :ref:`REST API of Orthanc <rest>`. It explains some advanced uses
+of the API.
+
+
+.. _jobs:
+
+Jobs
+----
+
+Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs
+are tasks to be done by Orthanc. Jobs are first added to a queue of
+pending tasks, and Orthanc will simultaneously a fixed number of jobs
+(check out :ref:`configuration option <configuration>`
+``ConcurrentJobs``). Once the jobs have been processed, they are tagged
+as successful or failed, and kept in a history (the size of this
+history is controlled by the ``JobsHistorySize`` option).
+
+Synchronous vs. asynchronous
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some calls to the REST API of Orthanc require time to be executed, and
+thus result in adding a job to the processing queue. This notably
+includes the following URIs:
+
+* :ref:`Modifying and anonymizing <anonymization>` DICOM instances.
+* Creating ZIP or media archives.
+* C-Move SCU (``/queries/.../retrieve``).
+* C-Store SCU (``/modalities/.../store``).
+* Sending to an Orthanc peer (``/peers/.../store``).
+* :ref:`Split/merge <split-merge>`.
+* Sending images using the :ref:`transfers accelerator <transfers>` plugin.
+
+Such REST API calls can be configured to be executed in a synchronous
+or an asynchronous mode:
+
+* **Synchronous calls** wait for the end of the execution of their
+  associated job. This is in general the default behavior.
+* **Asynchronous calls** end immediately and return a handle to their
+  associated job. It is up to the caller to monitor the end of the
+  execution by calling the jobs API.
+
+The choice between synchronous and asynchronous modes is done by
+setting the `Synchronous` field (or indifferently `Asynchronous`
+field) in the POST body of the call to the REST API. Note that the
+:ref:`transfers accelerator <transfers>` only run in the asynchronous
+mode.
+
+Even if it is more complex to handle, the asynchronous mode is highly
+recommended for jobs whose execution time can last over a dozen of
+seconds (typically, the creation of an archive or a network transfer).
+Indeed, this prevents timeouts in the HTTP protocol.
+
+
+
+
+.. _pdf:
+
+PDF
+---
+
+TODO