appendixCoordinatorAPI.tex

\chapter{RESTful APIs}\label{c:restful-apis}

\section{Coordinator's RESTful API}\label{s:coordinator-api}

\subsection[/smpc/histogram/numerical POST request]{\protect\icon{figures/post1.pdf}}\label{s:post1}

  This POST request initiates a secure computation for numerical\myslash continuous values dataset.
  \begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
       \item[Request:] Through the request's body, one can specify all the desired properties of the histograms to be computed.
  These include the attributes on which the histogram will be built (names and cells -- $\beta$ factor), the datasources from which data will be used, and a set of filters\myslash conditions that should hold for each data tuple taken into consideration when building the histogram.

  % For instance, for the CVI dataset (see section \ref{c:datasets}) a user specifies that he\myslash she wants to compute a histogram with $\beta = 4$ for term ``Patient Age''.

  The request's body is a \texttt{JSON} object with the following properties:

\begin{description}[labelwidth=6em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]

    \item[\texttt{attributes}:] {\color{red}\textit{required}} A list of JSON objects, corresponding to the attributes on which this histogram will be built.
    These JSON objects have the following keys:

    \begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
        \item[\texttt{name}:] {\color{red}\textit{required}} The name of the attribute (\textit{string}).

        \item[\texttt{cells}:] {\color{red}\textit{required}} The number of histogram cells ($\beta$ factor) to be created for this attribute (\textit{positive integer}).
    \end{description}

    \item[\texttt{datasources}:] {\color{blue}\textit{optional}} A list of the datasources (\textit{strings}) from which the histogram will be computed.
    If this key is left empty or not specified, all available datasources will be used.

    \item[\texttt{filters}:] {\color{blue}\textit{optional}} A JSON object containing a boolean operator and a list of filters\myslash conditions that should be met for each data tuple considered in the secure histogram computation.
    If this field is left blank or not specified, all data tuples will be used for the computation. The object has the following keys:

    \begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
        \item[\texttt{operator}:] {\color{red}\textit{required}} The boolean operator (\textit{string}) that will be applied between all the specified conditions that follow. One of \texttt{[AND, OR, XOR]}.
        In the case of multiple conditions, the operator is left\hyp associative.

        \item[\texttt{conditions}:] {\color{red}\textit{required}} The list of conditions that should be met by each data tuple in the computation.
        Each condition is represented as a JSON object with the following keys:

        \begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
            \item[\texttt{attribute}:] {\color{red}\textit{required}} The name of the attribute (\textit{string}).

            \item[\texttt{operator}:] {\color{red}\textit{required}} The condition's operator (\textit{string}). One of \texttt{[>, <, =]}.

            \item[\texttt{value}:] {\color{red}\textit{required}}  The attribute's value (\textit{string}).
        \end{description}

    \end{description}
\end{description}

 \begin{minipage}{\linewidth}
   Example (without \texttt{datasources} or \texttt{filters}):
 {
 \begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
   "attributes": [
       {
           "name": "Patient Age",
           "cells": "5"
       },
       {
           "name": "Height (cm)",
           "cells": "3"
       }
   ]
}
 \end{minted}
 \captionof{lstlisting}{Example 1 of /smpc/histogram/numerical POST request body}
 \label{sc:histogram-numerical-post-1}
 }
\end{minipage}

\ \\
 \begin{minipage}{\linewidth}
   Example (with \texttt{datasources} and \texttt{filters}):
 {
 \begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
   "attributes": [
       {
           "name": "Patient Age",
           "cells": "5"
       },
       {
           "name": "Height (cm)",
           "cells": "3"
       }
   ],
   "datasources": [
       "HospitalA",
       "HospitalB"
   ],
   "filters": {
       "operator": "AND",
       "conditions": [
           {
               "attribute": "Patient Age",
               "operator": ">",
               "value": "45"
           },
           {
               "attribute": "Weight (kg)",
               "operator": "<",
               "value": "90"
           }
       ]
   }
}
 \end{minted}
 \captionof{lstlisting}{Example 2 of /smpc/histogram/numerical POST request body}
 \label{sc:histogram-numerical-post-2}
 }
\end{minipage}

\item[Response:] The secure histogram computation is a potentially long running operation. For that reason the server's response to such a request is always \texttt{HTTP/1.1 202 Accepted} in case of correct request, along with a location in which one should periodically poll for the computation's status and\myslash or result. An example response can be found below.
\ \\

\begin{minipage}{\linewidth}
{
\texttt{Status: {\color{ForestGreen}\textbf{202 Accepted}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "location": "/smpc/queue?request=b171-3f4ade123374"
}
\end{minted}
\captionof{lstlisting}{Example 1 of /smpc/histogram/numerical response}
\label{sc:histogram-numerical-response-1}
}
\end{minipage}

In case of a malformed request the server responds with \texttt{HTTP/1.1 400 Bad Request} as seen below.\\

\begin{minipage}{\linewidth}
{
\texttt{Status: {\color{BrickRed}\textbf{400 Bad Request}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{bash}
Bad Request
\end{minted}
\captionof{lstlisting}{Example 2 of /smpc/histogram/numerical response}
\label{sc:histogram-numerical-response-2}
}
\end{minipage}

 \end{description}



\subsection[/smpc/histogram/categorical POST request]{\protect\icon{figures/post2.pdf}}\label{s:post2}
This POST request initiates a secure computation for categorical values dataset (MeSH).
Through the request's body, one can specify the desired MeSH terms.
The values the count of which will be computed are the children of the specified MeSH term from the MeSH ontology.

For example, if a user specifies that he\myslash she wants the counts for the MeSH term ``Age Groups" [M01.060], he\myslash she will get four counts back corresponding to the four children of ``Age Groups", namely ``Adolescent" [M01.060.057], ``Adult" [M01.060.116], ``Child" [M01. 060.406] and ``Infant" [M01.060.703].
If the specified MeSH terms are two, then the resulting counts will correspond to tuples of MeSH labels.
If the specified MeSH terms are three, the result will be triples, etc.

\begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
     \item[Request:] The request's body is a \texttt{JSON} object with the following properties:

\begin{description}[labelwidth=6em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]

    \item[\texttt{attributes}:] {\color{red}\textit{required}} A list of MeSH terms, corresponding to the attributes on which this histogram will be built.

    \item[\texttt{datasources}:] {\color{blue}\textit{optional}} A list of the datasources (\textit{strings}) from which the histogram will be computed.
    If this key is left empty or not specified, all available datasources will be used.

    \item[\texttt{filters}:] {\color{blue}\textit{optional}} A JSON object containing a boolean operator and a list of filters\myslash conditions that should be met for each data tuple considered in the secure histogram computation.
    If this field is left blank or not specified, all data tuples will be used for the computation.
    The object has the following keys:

    \begin{description}[labelwidth=6em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
        \item[\texttt{operator}:] {\color{red}\textit{required}} The boolean operator (\textit{string}) that will be applied between all the specified conditions that follow.
        One of \texttt{[AND, OR, XOR]}.
        In the case of multiple conditions, the operator is left\hyp associative.

        \item[\texttt{conditions}:] {\color{red}\textit{required}} The list of conditions that should be met by each data tuple in the computation.
        Note that the only filter that can be applied in categorical values is the equality checking.
        Each condition is represented as a JSON object with the following keys:

        \begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
            \item[\texttt{attribute}:] {\color{red}\textit{required}} The name of the attribute (\textit{string}).

            \item[\texttt{value}:] {\color{red}\textit{required}} The value that the selected attribute should be equal with (\textit{string}).
        \end{description}

    \end{description}
\end{description}

\begin{minipage}{\linewidth}
  Example (without \texttt{datasources} or \texttt{filters}):
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "attributes": [
        "M01.060",
        "M01.686.508"
    ]
}
\end{minted}
\captionof{lstlisting}{Example 1 of /smpc/histogram/categorical POST request body}
\label{sc:histogram-categorical-post-1}
}
\end{minipage}

\ \\
\begin{minipage}{\linewidth}
  Example (with \texttt{datasources} and \texttt{filters}):
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "attributes": [
        "M01.060",
        "M01.686.508"
    ],
    "datasources": [
        "HospitalA",
        "HospitalB"
    ],
    "filters": {
        "operator": "OR",
        "conditions": [
            {
                "attribute": "C14",
                "operator": "=",
                "value": "C14.280"
            },
            {
                "attribute": "C12",
                "operator": "=",
                "value": "C12.294"
            }
        ]
    }
}
\end{minted}
\captionof{lstlisting}{Example 2 of /smpc/histogram/categorical POST request body}
\label{sc:histogram-categorical-post-2}
}
\end{minipage}

\item[Response:] The server's response for the \texttt{/smpc/histogram/categorical} POST request is identical to that of \texttt{/smpc/histogram/numerical}. The server returns \texttt{HTTP / 1.1 202 Accepted} or \texttt{HTTP/1.1 400 Bad Request}. Examples for both cases can be seen in code snippets \ref{sc:histogram-numerical-response-1} and \ref{sc:histogram-numerical-response-2}.
 \end{description}



\subsection[/smpc/decisionTree POST request]{\protect\icon{figures/post3.pdf}}\label{s:post3}
Finally, this POST request is for computing a decision tree from either dataset.
The implemented classifiers are ID3 and C4.5, and one should specify which one to use in the request body along with the desired attributes.
Moreover, he\myslash she should specify the class-attribute, according to which the decision tree will occur.
\begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
     \item[Request:] The request's body is a \texttt{JSON} object with the following properties:

\begin{description}[labelwidth=9em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]

    \item[\texttt{attributes}:] {\color{red}\textit{required}} A list of MeSH terms, corresponding to the attributes on which this histogram will be built.
    These JSON objects have the following keys:

    \begin{description}[labelwidth=3em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
        \item[\texttt{name}:] {\color{red}\textit{required}} The name of the attribute (\textit{string}).

        \item[\texttt{cells}:] {\color{blue}\textit{optional}} The number of histogram cells ($\beta$ factor) to be created for this attribute (\textit{positive integer}).\footnote{In case, where C4.5 is selected as \texttt{classifier}, or the attribute is categorical, the \texttt{cells} object is omitted. \label{refnote1}}
    \end{description}

    \item[\texttt{classifier}:] {\color{blue}\textit{optional}} The name of the decision tree classifier to be used.
    Possible values are \{\texttt{ID3, C4.5}\}.
    If this key is left empty or not specified, the \texttt{ID3} classifier will be used by default.

    \item[\texttt{class\_attribute}:] {\color{red}\textit{required}} The attribute on which the classification will occur.
    \begin{description}[labelwidth=3em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
        \item[\texttt{name}:] {\color{red}\textit{required}} The name of the class attribute (\textit{string}).

        \item[\texttt{cells}:] {\color{blue}\textit{optional}} The number of histogram cells ($\beta$ factor) to be created for the class attribute (\textit{positive integer}).\footnote{In case, where the \texttt{class\_attribute} is categorical, the \texttt{cells} object is omitted. \label{refnote2}}
    \end{description}

    \item[\texttt{datasources}:] {\color{blue}\textit{optional}} A list of the datasources (\textit{strings}) from which the histogram will be computed.
    If this key is left empty or not specified, all available datasources will be used.

\end{description}

\begin{minipage}{\linewidth}
  Example (using ID3 as the classifier for categorical values):\\
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "attributes": [
        {
            "name": "C14"
        },
        {
            "name": "C12"
        },
        {
            "name": "M01.686"
        }
    ],
    "classifier": "ID3",
    "class_attribute": {
        "name": "M01.060"
    },
    "datasources": [
        "HospitalA",
        "HospitalB"
    ]
}
\end{minted}
\captionof{lstlisting}{Example 1 of /smpc/decisionTree POST request body for categorical values}
\label{sc:decisionTree-post-categorical-id3}
}
\end{minipage}

\ \\
\begin{minipage}{\linewidth}
  Example (using ID3 as the classifier for numerical values):\\
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "attributes": [
        {
            "name": "Height (cm)",
            "cells": "4"
        },
        {
            "name": "Weight (kg)",
            "cells": "5"
        },
        {
            "name": "Heart rate",
            "cells": "4"
        }
    ],
    "classifier": "ID3",
    "class_attribute": {
        "name": "Patient Age",
        "cells": "4"
    },
    "datasources": [
        "HospitalA",
        "HospitalB"
    ]
}
\end{minted}
\captionof{lstlisting}{Example 2 of /smpc/decisionTree POST request body for numerical values}
\label{sc:decisionTree-post-numerical-id3}
}
\end{minipage}
\ \\
\begin{minipage}{\linewidth}
  Example (using C4.5 as the classifier for numerical values):\\
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "attributes": [
        {
            "name": "Height (cm)"
        },
        {
            "name": "Weight (kg)"
        },
        {
            "name": "Heart rate"
        }
    ],
    "classifier": "C4.5",
    "class_attribute": {
        "name": "Patient Age",
        "cells": "4"
    },
    "datasources": [
        "HospitalA",
        "HospitalB"
    ]
}
\end{minted}
\captionof{lstlisting}{Example 3 of /smpc/decisionTree POST request body for categorical values}
\label{sc:decisionTree-post-categorical}
}
\end{minipage}

\item[Response:] The server's response for the \texttt{/smpc/decisionTree} POST request is the same as the ones described above. The server returns \texttt{HTTP/1.1 202 Accepted} or \texttt{HTTP/1.1 400 Bad Request}. Examples for both cases can be seen in code snippets \ref{sc:histogram-numerical-response-1} and \ref{sc:histogram-numerical-response-2}.

\end{description}



\subsection[/smpc/queue GET request]{\protect\icon{figures/get1.pdf}}\label{s:get1}
The \texttt{/smpc/queue} GET request is for checking the status and\myslash or result of a specified computation request (the aforementioned POST requests).
The status of an ongoing computation request can be accessed through the /smpc/queue GET request by specifying its id.
\begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
  \item[Request:] The only parameter this GET request accepts is the id of the desired computation request, as shown below.

\begin{minipage}{\linewidth}
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{html}
/smpc/queue?request=81c2-b9c0e5589ec0
\end{minted}
\captionof{lstlisting}{Example /smpc/queue GET request}
\label{sc:queue-request}
}
\end{minipage}
  \item[Response:] In case of a correct request, the server responds with \texttt{HTTP/1.1 200 OK} and the response body is a JSON object containing the specified computation's status, and possibly its current step or result which is a JSON object too.
The server's response body has the following structure.
\begin{description}[labelwidth=4em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
    \item [\texttt{status}:]{\color{red}\textit{required}} A string indicating the computation's status. One of [\texttt{running}, \texttt{succeeded}, \texttt{failed}, \texttt{notstarted}]
    \item [\texttt{step}:]{\color{blue}\textit{optional}} A string indicating the current step of the computation. This is present in case that the computation is in the running state.
    \item [\texttt{result}:]{\color{blue}\textit{optional}} A JSON object with the computation's result in case its status is succeeded. The JSON object contains a single key namely data which contains computation result.

    In case of private histogram computations the result is in the form of tuples (label, value) tuples, which are described here.
    \begin{description}[labelwidth=4em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
        \item [\texttt{label}:] A string, the value name corresponding to that count. Can be a tuple, triple etc. depending on the number of queried Mesh terms.
        \item [\texttt{value}:] An integer, the actual count for that value.
    \end{description}
    In case of private decision tree computations the result is in the form of a JSON object which has a key for each tree branch, and a value for the corresponding subtree that resides under that branch.
\end{description}

In case of a malformed request the server responds with \texttt{HTTP/1.1 400 Bad Request} as in \ref{sc:histogram-numerical-response-2}

Below you can find example responses for correct \texttt{/smpc/queue} GET requests.


\begin{minipage}{\linewidth}
  Example (successfully computed private categorical histogram):\\
{
\texttt{Status: {\color{ForestGreen}\textbf{200 OK}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "status": "succeeded",
    "result": {
        "data": [
            {
                "value": 78,
                "label": "Infant"
            },
            {
                "value": 63,
                "label": "Adolescent"
            },
            {
                "value": 9936,
                "label": "Adult"
            },
            {
                "value": 154,
                "label": "Child"
            }
        ]
    }
}
\end{minted}
\captionof{lstlisting}{Example /smpc/queue GET response body for a successful Age Groups (M01.060) histogram}
\label{sc:get-response-sucessful-1}
}
\end{minipage}
\ \\
\begin{minipage}{\linewidth}
  Example (successfully computed private numerical histogram):\\
{
\texttt{Status: {\color{ForestGreen}\textbf{200 OK}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "status": "succeeded",
    "result": {
        "data": [
            {
                "value": 84,
                "label": "[130.0, 144.0)"
            },
            {
                "value": 314,
                "label": "[144.0, 158.0)"
            },
            {
                "value": 428,
                "label": "[158.0, 172.0)"
            },
            {
                "value": 800,
                "label": "[172.0, 186.0)"
            },
            {
                "value": 374,
                "label": "[186.0, 200.0]"
            }
        ]
    }
}
\end{minted}
\captionof{lstlisting}{Example /smpc/queue GET response body for a successful Height(cm) histogram with $\beta = 5$}
\label{sc:get-response-sucessful-2}
}
\end{minipage}

\ \\
\begin{minipage}{\linewidth}
  Example (successfully computed private decision tree using C4.5):\\
{
\texttt{Status: {\color{ForestGreen}\textbf{200 OK}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "status": "succeeded",
    "result": {
        "data": {
            "Height (cm) <= 173.01": {
                "Weight (kg) > 68.56": {
                    "Heart rate > 81.50": "[18.00, 31.00)",
                    "Heart rate <= 81.50": "[70.00, 83.00)"
                },
                "Weight (kg) <= 68.56": {
                    "Heart rate > 70.50": "[31.00, 44.00)",
                    "Heart rate <= 70.50": "[18.00, 31.00)"
                }
            },
            "Height (cm) > 173.01": {
                "Weight (kg) > 87.70": {
                    "Heart rate > 94.00": "[18.00, 31.00)",
                    "Heart rate <= 94.00": "[31.00, 44.00)"
                },
                "Weight (kg) <= 87.70": {
                    "Heart rate <= 65.50": "[31.00, 44.00)",
                    "Heart rate > 65.50": "[57.00, 70.00)"
                }
            }
        }
    }
}
\end{minted}
\captionof{lstlisting}{Example /smpc/queue GET response body for a successfully computed private decision tree using C4.5 on Patient Age from categorical values}
\label{sc:get-response-sucessful-3}
}
\end{minipage}

\ \\
\begin{minipage}{\linewidth}
  Example (successfully computed private decision tree using ID3):\\
{
\texttt{Status: {\color{ForestGreen}\textbf{200 OK}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "status": "succeeded",
    "result": {
        "data": {
            "Height (cm) == [153.34, 176.67)": {
                "Heart rate == [95.33, 123.00)": "[34.25, 50.50)",
                "Heart rate == [67.67, 95.33)": "[18.00, 34.25)",
                "Heart rate == [40.00, 67.67)": "[18.00, 34.25)"
            },
            "Height (cm) == [130.01, 153.34)": {
                "Heart rate == [95.33, 123.00)": "[34.25, 50.50)",
                "Heart rate == [67.67, 95.33)": "[34.25, 50.50)",
                "Heart rate == [40.00, 67.67)": "[18.00, 34.25)"
            },
            "Height (cm) == [176.67, 200.00)": {
                "Heart rate == [95.33, 123.00)": "[18.00, 34.25)",
                "Heart rate == [67.67, 95.33)": "[34.25, 50.50)",
                "Heart rate == [40.00, 67.67)": "[34.25, 50.50)"
            }
        }
    }
}
\end{minted}
\captionof{lstlisting}{Example /smpc/queue GET response body for a successfully computed private decision tree using ID3 on Patient Age from categorical values}
\label{sc:get-response-sucessful-4}
}
\end{minipage}

\ \\
\begin{minipage}{\linewidth}
  Example (ongoing computation):\\
{
\texttt{Status: {\color{ForestGreen}\textbf{200 OK}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "status": "running",
    "step": "Securely importing data"
}
\end{minted}
\captionof{lstlisting}{Example /smpc/queue GET response body for an ongoing computation during secure import}
\label{sc:get-response-running}
}
\end{minipage}

\ \\
\begin{minipage}{\linewidth}
  Example (failed computation):\\
{
\texttt{Status: {\color{ForestGreen}\textbf{200 OK}}}
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "status": "failed"
}
\end{minted}
\captionof{lstlisting}{Example /smpc/queue GET response body for a failed computation}
\label{sc:get-response-failed}
}
\end{minipage}


\end{description}




\section{Data Providers' RESTful API}\label{s:data-providers-api}

\subsection[/smpc/import/numerical POST request]{\protect\icon{figures/post4.pdf}}\label{s:post4}
This POST request initiates a secure import for numerical\myslash continuous values dataset.
\begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
\item[Request:] Through the request's body, one can specify the desired attribute names (\textit{i.e.} columns of the dataset) to be imported.
For instance, an example for the CVI dataset (see section \ref{c:datasets}) is shown in Code \ref{sc:smpc-import-cvi}, in which a user specifies that he\myslash she wants to compute private analytics for attributes ``Patient Age'' and ``Heart rate''.

The request's body is a JSON object of the following form.

\begin{description}[labelwidth=6em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]

    \item[\texttt{attributes}:] {\color{red}\textit{required}} A list of attributes (\textit{strings}) on which this histogram will be built.

    \item[\texttt{datasource}:] {\color{red}\textit{required}} The name for the table of the SPMC cluster's encrypted database in which the data  will be imported.

\end{description}

\ \\
\begin{minipage}{\linewidth}
  Example (importing of some attribute from the CVI dataset):\\
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "attributes": [
        "Patient Age",
        "Heart rate"
    ],
    "datasource": "HospitalA"
}
\end{minted}
\captionof{lstlisting}{Example /smpc/import/numerical POST request body}
\label{sc:smpc-import-cvi}
}
\end{minipage}


\item[Response:] The server responds with \texttt{HTTP/1.1 200 OK} upon successful importing or with \texttt{HTTP/1.1 400 Bad Request} upon failure.
\end{description}




\subsection[/smpc/import/categorical POST request]{\protect\icon{figures/post5.pdf}}\label{s:post5}
This POST request initiates a secure import from datasets with categorical values dataset (MeSH).
\begin{description}[labelwidth=5em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]
\item[Request:] Through the request's body, one can specify the desired attribute names of the dataset to import.
The request for importing attributes from th MeSH dataset is similar to the the numerical one, in Code \ref{sc:smpc-import-cvi}, however in attributes should be specified by their MeSH codes, due to name ambiguity.

The request's body is a JSON object of the following form.

\begin{description}[labelwidth=6em, leftmargin=\dimexpr\labelwidth+\labelsep\relax]

    \item[\texttt{attributes}:] {\color{red}\textit{required}} A list of attributes (MeSH codes) on which this histogram will be built.

    \item[\texttt{datasource}:] {\color{red}\textit{required}} The name for the table of the SPMC cluster's encrypted database in which the data  will be imported.

\end{description}

\ \\
\begin{minipage}{\linewidth}
  Example (importing of some attribute from the CVI dataset):\\
{
\begin{minted}[framesep=3mm, frame=single, tabsize=2, breaklines, breaksymbolleft=, fontsize=\footnotesize]{json}
{
    "attributes": [
        "M01.060",
        "C14.280",
        "C14.240"
    ],
    "datasource": "HospitalA"
}
\end{minted}
\captionof{lstlisting}{Example /smpc/import/categorical POST request body}
\label{sc:smpc-import-mesh}
}
\end{minipage}

\item[Response:] The server responds with \texttt{HTTP/1.1 200 OK} upon successful importing or with \texttt{HTTP/1.1 400 Bad Request} upon failure.
\end{description}