6_Protocol_Definitions.tex

\chapter{Protocol Definitions}

\section{Input Data Validation}

\subsection{Name}
\label{protocoldef:inputvalidation:name}
First transform to lowercase and remove whitespaces everywhere in the String. Then check against\\
\verb|^[a-z0-9._\-]{3,40}$|

\subsection{Bcrypt Hash}
\label{protocoldef:inputvalidation:bcrypt}
\verb|^\$2[aby]?\$\d{1,2}\$[.\/A-Za-z0-9]{53}$|

\subsection{Email Address}
\label{protocoldef:inputvalidation:email}
\verb|/.+@.+\..+/i|\\
The user MMI should do a precheck on the email address. Example for NodeJs: \url{https://github.com/mailcheck/mailcheck}.

\subsection{Roles}
\label{protocoldef:inputvalidation:roles}
Get the actual set of allowed roles from the Auth Service at startup and check that the given value is in the returned array. See \ref{protocoldef:auth:api} for the API call to the Auth Service.
The JSON Value must be an Array with at least one entry. All entries must be a valid role. All entries have to be different, no repetitions of given roles are allow. They have to be filtered out if they exist.

\subsection{Auth Key}
\label{protocoldef:inputvalidation:authkey}
\verb|^[a-zA-Z0-9]{3,40}$|

\subsection{Owners}
\label{protocoldef:inputvalidation:owners}
Each entry of the array must validate successfully against \ref{protocoldef:inputvalidation:name}. No checking, if username is existing. The array must contain at least one element.

\subsection{Rubric Number}
\label{protocoldef:inputvalidation:rubricnumber}
The rubric number must be an integer >= 1 and <= 95.

\subsection{Rubric Label}
\label{protocoldef:inputvalidation:rubriclabel}
String with only \verb|a-zA-Z0-9_-| and max length of TBD.

\subsection{Transmitter Groups}
\label{protocoldef:inputvalidation:transmittergroup}
String with only \verb|a-zA-Z0-9_-| and max length of TBD.

\subsection{Rubric Cyclic Transmit Interval}
\label{protocoldef:inputvalidation:cyclictransmitinterval}
Integer value between 0 and 60*60*24*30.

\subsection{Description}
\label{protocoldef:inputvalidation:description}
The description has to be a string with arbitrary content. Max length 45 characters.

\subsection{RIC}
\label{protocoldef:inputvalidation:ric}
Integer value between 1 and $2^{21}-1$. There are reserved ranges that are not usable (i.e. 0-7, 2007664-2007671, 2045056-2045063).

\subsection{Function Bits}
\label{protocoldef:inputvalidation:function}
Integer value >= 0 and <= 3.

\subsection{Pager Type}
\label{protocoldef:inputvalidation:pagertype}
String
\todo{TBD}

\subsection{Transmitter Usage}
\label{protocoldef:inputvalidation:usage}
Valid values are \verb|wirerange| or \verb|personal|.

\subsection{Transmitter Timeslots}
\label{protocoldef:inputvalidation:timeslots}
A JSON Array of \textbf{exact} 16 boolean values.

\subsection{Transmitter Output Power}
\label{protocoldef:inputvalidation:power}
Float Value, > 0, round to 2 decimals. Max value 1000

\subsection{Coordinates}
\label{protocoldef:inputvalidation:coordinates}
JSON Array of two float, may be negative.
\todo{check ranges}

\subsection{Transmitter Antenna Type}
\label{protocoldef:inputvalidation:antennatype}
String
\todo{define}

\subsection{Transmitter Antenna Gain}
\label{protocoldef:inputvalidation:antennagain}
Float, can be negative min = -40, max = 40

\subsection{Transmitter Antenna Direction}
\label{protocoldef:inputvalidation:antennadirection}
Integer, if given as float -> round. Then modulo 360

\subsection{Transmitter Antenna Height}
\label{protocoldef:inputvalidation:antennaagl}
Integer, if given as float -> round. Always greater then 0.


\section{Microservices API}
\label{protocoldef:microservicesapi}

\subsection{Preamble}
All HTTP(s) communication should be compress with gzip to reduce network load. That's especially important for the answers to GET-calls of all entity's details.

See \hyperref[internalprog:microservices]{Microservices definition}.

\subsection{Filtering and pagination in detailed lists}
\label{protocoldef:filteringandpagination}
For the endpoints \verb|GET /users|, \verb|GET /nodes|, \verb|GET /transmitters| and \verb|GET /rubrics|, there are the following GET parameters available for pagination and filtering.

\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:usersdb}
  \begin{tabular}{|l|p{8.5cm}|} \hline
    Parameter                                & Description  \\ \hline \hline
    \verb|?skip=<n>&limit=<m>|               & Used for pagination, just output <m> entries and skip the first <n> ones. \\
                                             & Mapping to CouchDB: transparent \\ \hline
    \verb|?startkey="dh3wr"\&endkey="dl2ic"| & Get all entries with an \verb|_id| between \verb|dh3wr| and \verb|dl2ic|. \\
                                             & Mapping to CouchDB: transparent \\ \hline
    \verb|?startswith="dh3"|                 & Get all entries where the \verb|_id| starts with \verb|dh3|. Used for AJAX based search in tables on website. \\
                                             & Mapping to CouchDB: \verb|?startkey="dh3"&endkey="dh3\ufff0"| \\ \hline
  \end{tabular}
  \caption{Pagination and filtering syntax}
\end{table}

\textbf{Attention:} The parameter \verb|?include_docs=true| has to be included by the Microservice where it is stated in the detailed description below.\\

\newpage
\subsection{Database Service}
\subsubsection{GET /users}
\label{protocoldef:microservicesapi:database:getusers}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Returns all users (depending on the filtering in \ref{protocoldef:filteringandpagination} in JSON format. \\ \hline
    Permission         & \verb|user.read| \\ \hline
    Mapping to CouchDB & \verb|GET /users/_design/users/_view/byId?include_docs=true|\\ \hline
  \end{tabular}
\end{table}

\colorbox{red}{Special treatment for user database: The \texttt{password} field has always to be filtered out.}\\

\textbf{Auth response: \texttt{true}:}

\begin{lstlisting}
{
  "total_rows": 2,
  "offset": 0,
  "rows": [
    {
      "_id": "dh3wr",
      "_rev": "1-09352254509c9ddf86e80fd83868d557",
      "email": "ralf@secret.com",
      "roles": "user",
      "enabled": true,
      "created_on": "2018-07-08T11:50:02.168325Z",
      "created_by": "dl2ic"
      "changed_on": "2018-07-08T11:50:02.168325Z",
      "changed_by": "dl2ic
    }, ...
  ]
}
\end{lstlisting}
\textit{Whitelist:} Transparent, no filtering needed\\

\textbf{Auth response: \texttt{limited}:}\\
If \verb|_id == <username>| output the corresponding document transparent. All other document's\\
\textit{Whitelist:} \verb|_id, roles, enabled|

\begin{lstlisting}
{
  "total_rows": 2,
  "offset": 0,
  "rows": [
    {
      "_id": "dh3wr",
      "_rev": "1-09352254509c9ddf86e80fd83868d557",
      "email": "ralf@secret.com",
      "roles": ["user","admin"],
      "enabled": true,
      "created_on": "2018-07-08T11:50:02.168325Z",
      "created_by": "dl2ic"
      "changed_on": "2018-07-08T11:50:02.168325Z",
      "changed_by": "dl2ic
    },
    {
      "_id": "dl2abc",
      "roles": ["user"],
      "enabled": true
    }
  ]
}
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{GET /users/<username>}
\label{protocoldef:microservicesapi:database:getusers/username}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return details of <username> in JSON format. \\ \hline
    Permission         & \verb|user.read/<username>| \\ \hline
    Mapping to CouchDB & \verb|GET /users/<username>|\\ \hline
  \end{tabular}
\end{table}

\colorbox{red}{Special treatment for user database: The \texttt{password} field has always to be filtered out.}\\

\textbf{Auth response: \texttt{true}:}
\begin{lstlisting}
{
  "_id": "dh3wr",
  "_rev": "1-09352254509c9ddf86e80fd83868d557",
  "email": "ralf@secret.com",
  "roles": ["user"],
  "enabled": true,
  "created_on": "2018-07-08T11:50:02.168325Z",
  "created_by": "dl2ic",
  "changed_on": "2018-07-08T11:50:02.168325Z",
  "changed_by": "dl2ic
}
\end{lstlisting}

\textbf{Auth response: \texttt{limited}:}\\
If \verb|_id == <username>| output the corresponding document transparent.\\
If not:\\
\textit{Whitelist:} \verb|_id, roles, enabled|

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.


\subsubsection{GET /users/<usernames}
\label{protocoldef:microservicesapi:database:getusers/_usernames}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return just an JSON array of all enabled usernames. Used where selections have to be done on the website. \\ \hline
    Permission         & \verb|user.list| \\ \hline
    Mapping to CouchDB & \verb|GET /users/_design/users/_list/usernames/byId|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
\begin{lstlisting}
["dh3wr","dl2ic"]
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\subsubsection{GET /users/<username>/avatar.jpg}
\label{protocoldef:microservicesapi:database:getusers/username/avatar.jpg}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return the attachment called avatar.jpg for the given user \\ \hline
    Permission         & \verb|user.list| \\ \hline
    Mapping to CouchDB & \verb|GET /users/<username>/avatar.jpg|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
Get image with Content-Type: image/jpeg

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\newpage
\subsubsection{PUT /users - Add new user}
\label{protocoldef:microservicesapi:database:putusers/username_create}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Add a non-existing new user with \_id <username>\\ \hline
    Permission         & \verb|user.create| \\ \hline
    Mapping to CouchDB & \verb|PUT /users/<username>|\\ \hline
    Mandatory fields   & \verb|_id, password, email, roles, enabled| \\ \hline
    Field validation   & \verb|_id      :| \ref{protocoldef:inputvalidation:name}| \\
                       & \verb|password :| \ref{protocoldef:inputvalidation:bcrypt} \\
                       & \verb|email    :| \ref{protocoldef:inputvalidation:email} \\
                       & \verb|roles    :| \ref{protocoldef:inputvalidation:roles} \\
                       & \verb|enabled  :| boolean\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example content to add user dl6pt
\begin{lstlisting}
{
  "_id" : "dl6pt",
  "password": "$2y$12$lqUueRVo94f439Tt7zqrZOHPfm6YoBzNawWLLIykF3nMip3L6mxLK",
  "email": "ralf@secret.com",
  "roles": ["admin"],
  "enabled": true
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|created_*| information by database microservice:\\
\begin{lstlisting}
{
  "_id" : "dl6pt",
  "password": "$2y$12$lqUueRVo94f439Tt7zqrZOHPfm6YoBzNawWLLIykF3nMip3L6mxLK",
  "email": "ralf@secret.com",
  "roles": ["admin"],
  "enabled": true,
  "created_on": "2018-07-08T11:50:02.168325Z",
  "created_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\subsubsection{PUT /users - Edit existing user}
\label{protocoldef:microservicesapi:database:putusers/username_update}
Edit is differentiated from create by the presence of the \colorbox{red}{\texttt{\_rev}} field.

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Edit the existing user <username>.\\ \hline
    Permission         & \verb|user.update/<username>| \\ \hline
    Mapping to CouchDB & \verb|PUT /users/<username>|\\ \hline
    Mandatory fields   & \verb|_id, _rev| (\verb|_rev| has to be obtained as in \ref{protocoldef:microservicesapi:database:getusers/username})\\ \hline
    Optional fields    & \verb|password, email, roles, enabled| (minimum one)\\ \hline
    Field validation   & \verb|_id       :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|_rev      :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|password  :| \ref{protocoldef:inputvalidation:bcrypt} \\
                       & \verb|email     :| \ref{protocoldef:inputvalidation:email} \\
                       & \verb|roles     :| \ref{protocoldef:inputvalidation:roles} \\
                       & \verb|enabled   :| boolean\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example content to edit user dl6pt setting new password
\begin{lstlisting}
{
  "_id" : "dl6pt",
  "_rev": "1-09352254509c9ddf86e80fd83868d557",
  "password": "$2y$12$lqUueRVo94f439Tt7zqrZOHPfm6YoBzNawWLLIykF3nMip3L6mxLK"
}
\end{lstlisting}


Mapping to CouchDB with adding \verb|updated_*| information by database microservice:\\
\verb|PUT /users/<username>|
\begin{lstlisting}
{
  "_id" : "dl6pt",
  "_rev": "1-09352254509c9ddf86e80fd83868d557",
  "password": "$2y$12$lqUueRVo94f439Tt7zqrZOHPfm6YoBzNawWLLIykF3nMip3L6mxLK",
  "updated_on": "2018-07-08T11:50:02.168325Z",
  "updated_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\colorbox{red}{Special treatment if field \texttt{roles} is present:}\\
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Edit the existing user <username>\\ \hline
    \colorbox{red}{Permission}         & \verb|user.change_role/<username>| \\ \hline
    Mapping to CouchDB & \verb|PUT /users/<username>|\\ \hline
    Mandatory fields   & \verb|_id, _rev, roles| (\verb|_rev| has to be obtained as in \ref{protocoldef:microservicesapi:database:getusers/username}\\ \hline
    Optional fields    & \verb|password, email, roles, enabled| (minimum one)\\ \hline
    Field validation   & \verb|_id       :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|_rev      :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|password  :| \ref{protocoldef:inputvalidation:bcrypt} \\
                       & \verb|email     :| \ref{protocoldef:inputvalidation:email} \\
                       & \verb|roles     :| \ref{protocoldef:inputvalidation:roles} \\
                       & \verb|enabled   :| boolean\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Same behavior as before.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\subsubsection{PUT /users/<username>/avatar.jpg}
\label{protocoldef:microservicesapi:database:putusers/username/avatar.jpg}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Set the attachment called avatar.jpg for the given user \\ \hline
    Permission         & \verb|user.list| \\ \hline
    Mapping to CouchDB & \verb|PUT /users/<username>/avatar.jpg|\\ \hline
    Content in body    & Image as raw bytes \\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Transparent forwarding.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\subsubsection{DELETE /users/<username>?rev=<rev>}
\label{protocoldef:microservicesapi:database:deleteusers}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Delete user <username>\\ \hline
    Permission         & \verb|user.delete/<username>| \\ \hline
    Mapping to CouchDB & \verb|DELETE /users/<username>/avatar.jpg?rev=<rev>|\\ \hline
    Mandatory fields   & \verb|rev| as parameter (\verb|rev| has to be obtained as in  \ref{protocoldef:microservicesapi:database:getusers/username})\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Transparent forwarding.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\subsubsection{DELETE /users/<username>/avatar.jpg?rev=<rev>}
\label{protocoldef:microservicesapi:database:deleteuser/avatar.jpg}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Delete the attachment called avatar.jpg for the given user\\ \hline
    Permission         & \verb|user.delete/<username>| \\ \hline
    Mapping to CouchDB & \verb|DELETE /users/<username>?rev=<rev>|\\ \hline
    Mandatory fields   & \verb|rev| as parameter (\verb|rev| has to be obtained as in  \ref{protocoldef:microservicesapi:database:getusers/username})\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Transparent forwarding.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\newpage
\subsubsection{GET /nodes}
\label{protocoldef:microservicesapi:database:getnodes}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Returns all users (depending on the filtering in \ref{protocoldef:filteringandpagination} in JSON format. \\ \hline
    Permission         & \verb|node.read| \\ \hline
    Mapping to CouchDB & \verb|GET /users/_design/nodes/_view/byId?include_docs=true|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
\begin{lstlisting}
{
  "total_rows": 2,
  "offset": 0,
  "rows": [
    {
      "_id": "db0sda-dc1",
      "_rev": "1-cf7d2abfe193f476888be7108a0f548f",
      "auth_key": "8PL9eJXccQ6X9Yq"
      "coordinates": [34.123456, -23.123456],
      "description": "some words about that node",
      "hamcloud": true,
      "created_on": "2018-07-03T08:00:52.786458Z",
      "created_by": "dh3wr",
      "changed_on": "2018-07-03T08:00:52.786458Z",
      "changed_by": "dh3wr",
      "owners": ["dl1abc","dh3wr","dl2ic"]
    },
    {
      "_id": "db0sda-dc2",
      "_rev": "1-ee070b17db9c3c58658d10fdedad2f48",
      "auth_key": "73mxX4JLttzmVZ2"
      "coordinates": [34.123456, -23.123456],
      "description": "some words about that node",
      "hamcloud": true,
      "created_on": "2018-07-03T08:00:52.786458Z",
      "created_by":"dh3wr",
      "changed_on": "2018-07-03T08:00:52.786458Z",
      "changed_by":"dh3wr",
      "owners": ["dl1abc","dh3wr","dl2ic"]
    }
  ]
}
\end{lstlisting}

\textbf{Auth response: \texttt{limited}:}\\
The output rows have to be checked, if the asking username is in the \texttt{owners} array.\\

If yes: return the complete row.\\
If not: return just the whitelisted fields:\\

\textit{Whitelist:} \_id, coordinates, description, hamcloud, owners\\

Example (here dh3wr is asking with limited permission):
\begin{lstlisting}
{
  "total_rows": 2,
  "offset": 0,
  "rows": [

    {
      "_id": "db0sda-dc1",
      "coordinates": [34.123456, -23.123456],
      "description": "some words about that node",
      "hamcloud": true,
      "owners": ["dl1abc","dl2ic"]
    },
    {
      "_id": "db0sda-dc2",
      "_rev": "1-ee070b17db9c3c58658d10fdedad2f48",
      "auth_key": "73mxX4JLttzmVZ2"
      "coordinates": [34.123456, -23.123456],
      "description": "some words about that node",
      "hamcloud": true,
      "created_on": "2018-07-03T08:00:52.786458Z",
      "created_by":"dh3wr",
      "changed_on": "2018-07-03T08:00:52.786458Z",
      "changed_by":"dh3wr",
      "owners": ["dl1abc","dh3wr","dl2ic"]
    }
  ]
}
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{GET /nodes/<nodename>}
\label{protocoldef:microservicesapi:database:getnodes/nodename}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return details of <nodename> in JSON format. \\ \hline
    Permission         & \verb|node.read/<nodename>| \\ \hline
    Mapping to CouchDB & \verb|GET /users/<nodename>|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\

\begin{lstlisting}
{
  "_id": "db0sda-dc2",
  "_rev": "1-ee070b17db9c3c58658d10fdedad2f48",
  "auth_key": "73mxX4JLttzmVZ2"
  "coordinates": [34.123456, -23.123456],
  "description": "some words about that node",
  "hamcloud": true,
  "created_on": "2018-07-03T08:00:52.786458Z",
  "created_by":"dh3wr",
  "changed_on": "2018-07-03T08:00:52.786458Z",
  "changed_by":"dh3wr",
  "owners": ["dl1abc","dh3wr","dl2ic"]
}
\end{lstlisting}

\textbf{Auth response: \texttt{limited}:}\\
The output has be checked, if the asking username is in the \texttt{owners} array.\\

If yes: return the complete output from CouchDB.\\
If not: return just the whitelisted fields:\\

\textit{Whitelist:} \_id, coordinates, description, hamcloud, owners\\

Example (here dh3wr is asking with limited permission):
\begin{lstlisting}
{
      "_id": "db0sda-dc1",
      "coordinates": [34.123456, -23.123456],
      "description": "some words about that node",
      "hamcloud": true,
      "owners": ["dl1abc","dl2ic"]
}
\end{lstlisting}

\newpage
\subsubsection{GET /nodes/\_names}
\label{protocoldef:microservicesapi:database:getnodes/_names}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return just an JSON array of all nodes. Used where selections have to be done on the website. \\ \hline
    Permission         & \verb|nodes.list| \\ \hline
    Mapping to CouchDB & \verb|GET /nodes/_design/nodes/_list/names/byId|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
\begin{lstlisting}
["db0sda-dc2","db0sda-dc3"]
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\subsubsection{GET /nodes/\_descriptions}
\label{protocoldef:microservicesapi:database:getnodes/_descriptions}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return just an JSON array of all nodenames and their description, sorted as a list. Used where descriptive selections have to be done on the website. \\ \hline
    Permission         & \verb|nodes.list| \\ \hline
    Mapping to CouchDB & \verb|GET /nodes/_design/nodes/_list/descriptions/descriptions|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
\begin{lstlisting}
[
  {
    "_id": "db0sda-dc1",
    "description": "some words about that node"
  },
  {
    "_id": "db0sda-dc2",
    "description": "some words about that node"
  }
]
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{PUT /nodes - Add new node}
\label{protocoldef:microservicesapi:database:putnodes/node_create}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Add a non-existing new node with \_id <nodename>\\ \hline
    Permission         & \verb|node.create| \\ \hline
    Mapping to CouchDB & \verb|PUT /nodes/<nodesname>|\\ \hline
    Mandatory fields   & \verb|_id, auth_key, hamcloud, owners, description, coordinates| \\ \hline
    Field validation   & \verb|_id         :| \ref{protocoldef:inputvalidation:name} \\
                       & \verb|auth_key    :| \ref{protocoldef:inputvalidation:authkey} \\
                       & \verb|hamcloud    :| boolean \\
                       & \verb|owners      :| \ref{protocoldef:inputvalidation:owners} \\
                       & \verb|coordinates :| \ref{protocoldef:inputvalidation:coordinates}\\
                       & \verb|description :| \ref{protocoldef:inputvalidation:description}\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example content to add node db0sda-dc2
\begin{lstlisting}
{
  "_id": "db0sda-dc2",
  "auth_key": "73mxX4JLttzmVZ2"
  "coordinates": [34.123456, -23.123456],
  "description": "some words about that node",
  "hamcloud": true,
  "owners": ["dl1abc","dh3wr","dl2ic"]
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|created_*| information by database microservice:\\
\begin{lstlisting}
{
  "_id": "db0sda-dc2",
  "auth_key": "73mxX4JLttzmVZ2"
  "coordinates": [34.123456, -23.123456],
  "description": "some words about that node",
  "hamcloud": true,
  "owners": ["dl1abc","dh3wr","dl2ic"],
  "created_on": "2018-07-08T11:50:02.168325Z",
  "created_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{PUT /nodes - Edit existing node}
\label{protocoldef:microservicesapi:database:putnodes/node_update}
Edit is differentiated from create by the presence of the \colorbox{red}{\texttt{\_rev}} field.

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Edit the existing node <nodename>.\\ \hline
    Permission         & \verb|node.update/<nodename>| \\ \hline
    Mapping to CouchDB & \verb|PUT /nodes/<nodename>|\\ \hline
    Mandatory fields   & \verb|_id, _rev| (\verb|_rev| has to be obtained as in \ref{protocoldef:microservicesapi:database:getnodes/nodename})\\ \hline
    Optional fields    & \verb|auth_key, hamcloud, owners, description, coordinates| (minimum one)\\ \hline
    Field validation   & \verb|_id         :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|_rev        :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|auth_key    :| \ref{protocoldef:inputvalidation:authkey} \\
                       & \verb|hamcloud    :| boolean \\
                       & \verb|owners      :| \ref{protocoldef:inputvalidation:owners} \\
                       & \verb|coordinates :| \ref{protocoldef:inputvalidation:coordinates}\\
                       & \verb|description :| \ref{protocoldef:inputvalidation:description}\\ \hline

  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
User to Database-Service: Example content to edit user dl6pt setting new password
\begin{lstlisting}
{
  "_id": "db0sda-dc2",
  "_rev": "1-ee070b17db9c3c58658d10fdedad2f48",
  "auth_key": "73mxX4JLttzmVZ2"
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|updated_*| information by database microservice:\\
\verb|PUT /users/<username>|
\begin{lstlisting}
{
  "_id": "db0sda-dc2",
  "_rev": "1-ee070b17db9c3c58658d10fdedad2f48",
  "auth_key": "73mxX4JLttzmVZ2",
  "updated_on": "2018-07-08T11:50:02.168325Z",
  "updated_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\subsubsection{DELETE /nodes/<nodename>?rev=<rev>}
\label{protocoldef:microservicesapi:database:deletenode}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Delete node <nodename>\\ \hline
    Permission         & \verb|node.delete/<nodename>| \\ \hline
    Mapping to CouchDB & \verb|DELETE /nodes/<nodename>?rev=1-093...|\\ \hline
    Mandatory fields   & \verb|rev| as parameter (\verb|rev| has to be obtained as in  \ref{protocoldef:microservicesapi:database:getnodes/nodename})\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Transparent forwarding.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\todo{Maybe the transmitter service should inform the connected transmitters of the deleted node to do a switch-over?}

\newpage
\subsubsection{GET /rubrics}
\label{protocoldef:microservicesapi:database:rubrics}

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Returns all rubrics (depending on the filtering in \ref{protocoldef:filteringandpagination} in JSON format. \\ \hline
    Permission         & \verb|rubric.read| \\ \hline
    Mapping to CouchDB & \verb|GET /rubrics/_design/rubrics/_view/byId?include_docs=true|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
\begin{lstlisting}
{
  "total_rows": 1,
  "offset": 0,
  "rows": [
    {
      "_id": "dx-kw",
      "_rev": "1-166c3257894d0aea8ee68c1861ca508a",
      "number": 4,
      "description": "DX Cluster Spots KW",
      "label": "DX KW",
      "transmitter_groups": [
        "dl-hh"
      ],
      "transmitters": [
        "db0abc"
      ],
      "cyclic_transmit": false,
      "cyclic_transmit_interval": 0,
      "owner": [
        "dh3wr",
        "dl1abc"
      ]
    }
  ]
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{GET /rubrics/\_view/byNumber?startkey=<n>\&endkey=<m>}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Get the output as in section \ref{protocoldef:microservicesapi:database:rubrics}, but just for rubric numbers between <n> and <m>. \\ \hline
    Permission         & \verb|rubric.read| \\ \hline
    Mapping to CouchDB & \verb|GET /rubrics/\_view/byNumber?startkey=<n>\&endkey=<m>| \\ \hline
    Field validation   & \verb|startkey :| \ref{protocoldef:inputvalidation:rubricnumber} \\
                       & \verb|endkey   :| \ref{protocoldef:inputvalidation:rubricnumber} \\ \hline
  \end{tabular}
\end{table}
Auth handling is the same as in section \ref{protocoldef:microservicesapi:database:rubrics}.


\subsubsection{GET /rubrics/\_view/byTransmitter?key=<transmittername>}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Get the output as in section \ref{protocoldef:microservicesapi:database:rubrics}, but just for rubrics that contain <transmittername> in the \verb|"transmitters"| array. \\ \hline
    Permission         & \verb|rubric.read| \\ \hline
    Mapping to CouchDB & \verb|GET /rubrics/\_view/byTransmitter?key=<transmittername>| \\ \hline
  \end{tabular}
\end{table}
Auth handling is the same as in section \ref{protocoldef:microservicesapi:database:rubrics}.

\subsubsection{GET /rubrics/\_view/byTransmitterGroup?key=<groupname>}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Get the output as in section \ref{protocoldef:microservicesapi:database:rubrics}, but just for rubrics that contains <groupname> in the \verb|"transmitter_groups"| array. \\ \hline
    Permission         & \verb|rubric.read| \\ \hline
    Mapping to CouchDB & \verb|GET /rubrics/\_view/byTransmitterGroup?key=<groupname>| \\ \hline
  \end{tabular}
\end{table}
Auth handling is the same as in section \ref{protocoldef:microservicesapi:database:rubrics}.

\subsubsection{GET /rubrics/\_view/withCyclicTransmit}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Get the output as in section \ref{protocoldef:microservicesapi:database:rubrics}, but just for rubric that have the cyclic transmit flag enabled. \\ \hline
    Permission         & \verb|rubric.read| \\ \hline
    Mapping to CouchDB & \verb|GET /rubrics/\_view/withCyclicTransmit| \\ \hline
  \end{tabular}
\end{table}
Auth handling is the same as in section \ref{protocoldef:microservicesapi:database:rubrics}.

\newpage
\subsubsection{GET /rubrics/<rubricname>}
\label{protocoldef:microservicesapi:database:getrubrics/rubricname}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return details of <rubricname> in JSON format. This does \textbf{not} include the content of the 10 rubric message slots. \\ \hline
    Permission         & \verb|rubric.read/<username>| \\ \hline
    Mapping to CouchDB & \verb|GET /rubric/<username>| \\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
\begin{lstlisting}
{
  "_id": "dx-kw",
  "_rev": "1-166c3257894d0aea8ee68c1861ca508a",
  "number": 4,
  "description": "DX Cluster Spots KW",
  "label": "DX KW",
  "transmitter_groups": [
    "dl-hh"
  ],
  "transmitters": [
    "db0abc"
  ],
  "cyclic_transmit": false,
  "cyclic_transmit_interval": 0,
  "owner": [
    "dh3wr",
    "dl1abc"
  ]
}
\end{lstlisting}


\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\subsubsection{GET /rubrics/\_names}
\label{protocoldef:microservicesapi:database:getrubrics/_names}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return just an JSON array of all rubricnames. Used where selections have to be done on the website. \\ \hline
    Permission         & \verb|rubrics.list| \\ \hline
    Mapping to CouchDB & \verb|GET /rubrics/_design/rubrics/_list/names/byId|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
\begin{lstlisting}
["dl-hh", "dl-nw"]
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{GET /rubrics/\_descriptions}
\label{protocoldef:microservicesapi:database:getrubrics/_descriptions}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return just an JSON array of all rubricnames their description in a JSON Array. Used where selections have to be done on the website. \\ \hline
    Permission         & \verb|rubrics.list| \\ \hline
    Mapping to CouchDB & \verb|GET /rubrics/_design/rubrics/_list/descriptions/descriptions|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
\begin{lstlisting}
[
  {
    "_id": "dl-hh",
    "description": "Germany, Hamburg"
  },
  {
    "_id": "dl-by",
    "description": "Bavaria"
  }
]
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\subsubsection{PUT /rubrics - Add new rubric}
\label{protocoldef:microservicesapi:database:putrubrics/rubrics_create}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Add a non-existing new rubric with \_id <rubricname>\\ \hline
    Permission         & \verb|rubric.create| \\ \hline
    Mapping to CouchDB & \verb|PUT /rubrics/<rubricsname>|\\ \hline
    Mandatory fields   & \verb|_id, number, description, label, transmitter_groups,| \\
                       & \verb|cyclic_transmit, cyclic_transmit_interval, owners| \\ \hline
    Field validation   & \verb|_id                      :| \ref{protocoldef:inputvalidation:name}| \\
                       & \verb|number                   :| \ref{protocoldef:inputvalidation:rubricnumber} \\
                       & \verb|description              :| \ref{protocoldef:inputvalidation:description} \\
                       & \verb|label                    :| \ref{protocoldef:inputvalidation:rubriclabel} \\
                       & \verb|transmitter_groups       :| \ref{protocoldef:inputvalidation:transmittergroup} \\
                       & \verb|cyclic_transmit          :| boolean \\
                       & \verb|cyclic_transmit_interval :| \ref{protocoldef:inputvalidation:cyclictransmitinterval} \\
                       & \verb|owners                   :| \ref{protocoldef:inputvalidation:owners} \\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example content to add rubric dx-kw
\begin{lstlisting}
{
  "_id": "dx-kw",
  "number": 4,
  "description": "DX Cluster Spots KW",
  "label": "DX KW",
  "transmitter_groups": [
    "dl-hh"
  ],
  "transmitters": [
    "db0abc"
  ],
  "cyclic_transmit": false,
  "cyclic_transmit_interval": 0,
  "owners": [
    "dh3wr",
    "dl1abc"
  ]
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|created_*| information by database microservice:\\
\begin{lstlisting}
{
  "_id": "dx-kw",
  "number": 4,
  "description": "DX Cluster Spots KW",
  "label": "DX KW",
  "transmitter_groups": [
    "dl-hh"
  ],
  "transmitters": [
    "db0abc"
  ],
  "cyclic_transmit": false,
  "cyclic_transmit_interval": 0,
  "owners": [
    "dh3wr",
    "dl1abc"
  ],
  "created_on": "2018-07-08T11:50:02.168325Z",
  "created_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\subsubsection{PUT /rubrics - Edit existing rubric}
\label{protocoldef:microservicesapi:database:putrubrics/rubrics_update}
Edit is differentiated from create by the presence of the \colorbox{red}{\texttt{\_rev}} field.

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Edit the existing rubric <rubricname>.\\ \hline
    Permission         & \verb|rubric.update/<rubricname>| \\ \hline
    Mapping to CouchDB & \verb|PUT /rubrics/<rubricsname>|\\ \hline
    Mandatory fields   & \verb|_id, _rev| (\verb|_rev| has to be obtained as in \ref{protocoldef:microservicesapi:database:getrubrics/rubricname})\\ \hline
    Optional fields    & \verb|number, description, label, transmitter_groups,| \\
                       & \verb|cyclic_transmit, cyclic_transmit_interval, owners| (minimum one)\\ \hline
    Field validation   & \verb|_id                      :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|_rev                     :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|number                   :| \ref{protocoldef:inputvalidation:rubricnumber} \\
                       & \verb|description              :| \ref{protocoldef:inputvalidation:description} \\
                       & \verb|label                    :| \ref{protocoldef:inputvalidation:rubriclabel} \\
                       & \verb|transmitter_groups       :| \ref{protocoldef:inputvalidation:transmittergroup} \\
                       & \verb|cyclic_transmit          :| boolean \\
                       & \verb|cyclic_transmit_interval :| \ref{protocoldef:inputvalidation:cyclictransmitinterval} \\
                       & \verb|owners                   :| \ref{protocoldef:inputvalidation:owners} \\ \hline

  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
User to Database-Service: Example content to edit to add rubric dx-kw changing the description
\begin{lstlisting}
{
  "_id": "db0sda-dc2",
  "_rev": "1-ee070b17db9c3c58658d10fdedad2f48",
  "description": "New DX Cluster Spots KW",
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|updated_*| information by database microservice:\\
\begin{lstlisting}
{
  "_id": "db0sda-dc2",
  "_rev": "1-ee070b17db9c3c58658d10fdedad2f48",
  "description": "New DX Cluster Spots KW",
  "updated_on": "2018-07-08T11:50:02.168325Z",
  "updated_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\subsubsection{DELETE /rubrics/<rubricname>?rev=<rev>}
\label{protocoldef:microservicesapi:database:deleterubric}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Delete node <rubricname>\\ \hline
    Permission         & \verb|rubric.delete/<rubricname>| \\ \hline
    Mapping to CouchDB & \verb|DELETE /rubrics/<rubricname>?rev=<rev>|\\ \hline
    Mandatory fields   & \verb|rev| as parameter (\verb|rev| has to be obtained as in  \ref{protocoldef:microservicesapi:database:getrubrics/rubricname})\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Transparent forwarding.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{GET /subscribers}
\label{protocoldef:microservicesapi:database:subscribers}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Returns all subscribers (depending on the filtering in \ref{protocoldef:filteringandpagination} in JSON format. \\ \hline
    Permission         & \verb|subscriber.read| \\ \hline
    Mapping to CouchDB & \verb|GET /subscribers/_design/subscribers/_view/byId?include_docs=true|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true} or \texttt{limited}:}\\
\begin{lstlisting}

\begin{lstlisting}
{
  "total_rows": 1,
  "offset": 0,
  "rows": [
    {
      "_id": "dl1abc",
      "_rev": "1-44182aeb25815b19babe1c0a6bb95e68",
      "description": "Peter",
      "pagers": [
        {
          "ric": 123456,
          "function": 3,
          "name": "Peters Alphapoc",
          "type": "alphaPpoc",
          "enabled": true
        }
      ],
      "third_party_services": [
        "APRS",
        "BM"
      ],
      "owners": [
        "dh3wr",
        "dl1abc"
      ],
      "groups": [
        "rwth-afu"
      ]
    }
  ]
}
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{GET /subscribers/<subscribername>}
\label{protocoldef:microservicesapi:database:getsubscribers/subscribername}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return details of <subscribername> in JSON format. \\ \hline
    Permission         & \verb|subscriber.read/<subscribername>| \\ \hline
    Mapping to CouchDB & \verb|GET /subscriber/<subscribername>| \\ \hline
  \end{tabular}
\end{table}


\textbf{Auth response: \texttt{true} or \texttt{limited}:}\\
\begin{lstlisting}
{
  "_id": "dl1abc",
  "_rev": "1-44182aeb25815b19babe1c0a6bb95e68",
  "description": "Peter",
  "pagers": [
    {
      "ric": 123456,
      "function": 3,
      "name": "Peters Alphapoc",
      "type": "alphaPpoc",
      "enabled": true
    }
  ],
  "third_party_services": [
    "APRS",
    "BM"
  ],
  "owners": [
    "dh3wr",
    "dl1abc"
  ],
  "groups": [
    "rwth-afu"
  ]
}
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{GET /subscribers/\_names}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return just an JSON array of all subscribers. Used where selections have to be done on the website. \\ \hline
    Permission         & \verb|rubric.list| \\ \hline
    Mapping to CouchDB & \verb|GET /subscribers/_design/subscribers/_list/names/byId| \\ \hline
  \end{tabular}
\end{table}


\textbf{Auth response: \texttt{true} or \texttt{limited}:}\\
\begin{lstlisting}
["dh3wr","dl2ic"]
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.


\subsubsection{GET /subscribers/\_descriptions}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return just an JSON array of all subscribers and their descriptions. Used where selections have to be done on the website. \\ \hline
    Permission         & \verb|rubric.list| \\ \hline
    Mapping to CouchDB & \verb|GET /subscribers/_design/subscribers/_list/descriptions/descriptions| \\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true} or \texttt{limited}:}\\
\begin{lstlisting}
[
  {
    "_id": "dh3wr",
    "description": "Ralf"
  },
  {
    "_id": "dl2ic",
    "description": "Thomas"
  }
]
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.

\subsubsection{GET /subscriber\_groups}
\label{protocoldef:microservicesapi:database:getsubscriber/_groups}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Returns an array of existing subscribers\_goups tags in JSON format. Used where selections have to be done on the website. \\ \hline
    Permission         & \verb|subscriber_groups.list| \\ \hline
    Mapping to CouchDB & \verb|GET /subscribers/??? unknown FIXME|\\ \hline
  \end{tabular}
\end{table}
\todo{Generate CouchDB request}

\textbf{Auth response: \texttt{true} or \texttt{limited}:}
\begin{lstlisting}
["dl.OV-G01","dl.rwth-afu"]
\end{lstlisting}

\textbf{Auth response: \texttt{false}}\\
Send \verb|403 Forbidden|.


\newpage
\subsubsection{PUT /subscribers - Add new subscriber}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Add a non-existing new subscriber with \_id <subscribername>\\ \hline
    Permission         & \verb|subscriber.create| \\ \hline
    Mapping to CouchDB & \verb|PUT /subscribers/<subscribername>|\\ \hline
    Mandatory fields   & \verb|_id, description, pagers, ric, function, type| \\
                       & \verb|enabled, third_party_services, owners, groups| \\ \hline
    Field validation   & \verb|_id                  :| \ref{protocoldef:inputvalidation:name} \\
                       & \verb|description          :| \ref{protocoldef:inputvalidation:description}\\
                       & \verb|pagers               :| The key for the array, must be present.\\
                       & \verb|ric                  :| \ref{protocoldef:inputvalidation:ric} \\
                       & \verb|function             :| \ref{protocoldef:inputvalidation:function} \\
                       & \verb|type                 :| \ref{protocoldef:inputvalidation:pagertype} \\
                       & \verb|enabled              :|  boolean \\
                       & \verb|third_party_services :| The key for the array, must be present \\
                       & \verb|owners               :| \ref{protocoldef:inputvalidation:owners} \\
                       & \verb|groups               :| The key for the array, must be present \\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example content to add subscriber dl1abc
\begin{lstlisting}
{
  "_id": "dl1abc",
  "description": "Peter",
  "pagers": [
    {
      "ric": 123456,
      "function": 3,
      "name": "Peters Alphapoc",
      "type": "alphaPpoc",
      "enabled": true
    }
  ],
  "third_party_services": [
   "APRS",
   "BM"
  ],
  "owners": [
    "dh3wr",
    "dl1abc"
  ],
  "groups": []
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|created_*| information by database microservice:\\
\begin{lstlisting}
\begin{lstlisting}
{
  "_id": "dl1abc",
  "description": "Peter",
  "pagers": [
    {
      "ric": 123456,
      "function": 3,
      "name": "Peters Alphapoc",
      "type": "alphaPpoc",
      "enabled": true
    }
  ],
  "third_party_services": [
   "APRS",
   "BM"
  ],
  "owner": [
    "dh3wr",
    "dl1abc"
  ],
  "groups": [],
  "created_on": "2018-07-08T11:50:02.168325Z",
  "created_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\subsubsection{PUT /subscribers - Edit existing subscriber}
Edit is differentiated from create by the presence of the \colorbox{red}{\texttt{\_rev}} field.

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Add a edit a existing subscriber with \_id <subscribername>\\ \hline
    Permission         & \verb|subscriber.update| \\ \hline
    Mapping to CouchDB & \verb|PUT /subscribers/<subscribername>|\\ \hline
    Mandatory fields   & \verb|_id, _rev| \\ \hline
    Optional fields    & \verb|description, pagers, ric, function, type, enabled,| \\
                       & \verb|third_party_services, owners, groups (minimum one, if it's pagers, the| \\
                       & \verb|complete pagers array has to be sent.| \\ \hline
    Field validation   & \verb|_id                  :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|_rev                 :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|description          :| \ref{protocoldef:inputvalidation:description}\\
                       & \verb|pagers               :| The key for the array, must be present.\\
                       & \verb|ric                  :| \ref{protocoldef:inputvalidation:ric} \\
                       & \verb|function             :| \ref{protocoldef:inputvalidation:function} \\
                       & \verb|type                 :| \ref{protocoldef:inputvalidation:pagertype} \\
                       & \verb|enabled              :| boolean \\
                       & \verb|third_party_services :| The key for the array, must be present \\
                       & \verb|owners               :| \ref{protocoldef:inputvalidation:owners} \\
                       & \verb|groups               :| The key for the array, must be present \\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example content to edit the description of subscriber dl1abc
\begin{lstlisting}
{
  "_id": "dl1abc",
  "_rev": "1-44182aeb25815b19babe1c0a6bb95e68",
  "description": "Peter",
\end{lstlisting}


Mapping to CouchDB with adding \verb|updated_*| information by database microservice:\\
\begin{lstlisting}
{
  "_id": "dl1abc",
  "_rev": "1-44182aeb25815b19babe1c0a6bb95e68",
  "description": "Peter",
  "updated_on": "2018-07-08T11:50:02.168325Z",
  "updated_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{DELETE /subscribers/<subscribername>?rev=<rev>}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Delete subscriber <subscribername>\\ \hline
    Permission         & \verb|subscriber.delete/<subscribername>| \\ \hline
    Mapping to CouchDB & \verb|DELETE /subscribers/<subscribername>?rev=<rev>|\\ \hline
    Mandatory fields   & \verb|rev| as parameter (\verb|rev| has to be obtained as in  \ref{protocoldef:microservicesapi:database:getsubscribers/subscribername})\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Transparent forwarding.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.


\subsubsection{GET /transmitters/\_names}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Return an JSON array of all transmitter names. Used where selections have to be done on the website\\ \hline
    Permission         & \verb|transmitter.list| \\ \hline
    Mapping to CouchDB & \verb|GET /transmitters/_design/transmitters/_list/names/byId|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true} or \texttt{limited}:}\\
\begin{lstlisting}
["db0sda", "db0wa"]
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.

\subsubsection{GET /transmitters/\_groups}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Returns a JSON array of used transmitter groups tags from all known transmitters. Used for a suggestion of already existing transmitter group tags on the website.\\ \hline
    Permission         & \verb|transmitter.list| \\ \hline
    Mapping to CouchDB & \verb|GET /transmitters/_design/transmitters/_list/groups/byGroup?group_level=4|\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true} or \texttt{limited}:}\\
\begin{lstlisting}
["dl.nw.koeln.aachen","dxluster.dl","testinggroup"]
\end{lstlisting}

\textbf{Auth response: \texttt{false}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{PUT /transmitters - Add new transmitter}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Add a non-existing new subscriber with \_id <subscribername>\\ \hline
    Permission         & \verb|subscriber.create| \\ \hline
    Mapping to CouchDB & \verb|PUT /subscribers/<subscribername>|\\ \hline
    Mandatory fields   & \verb|_id, usage, timeslots, power, owners, groups,| \\
                       & \verb|coordinates, aprs_broadcast, enabled, auth_key|\\
                       & \verb|antenna, type, gain, direction, agl| \\ \hline
    Field validation   & \verb|_id            :| \ref{protocoldef:inputvalidation:name} \\
                       & \verb|usage          :| \ref{protocoldef:inputvalidation:usage}\\
                       & \verb|timeslots      :| \ref{protocoldef:inputvalidation:timeslots}\\
                       & \verb|power          :| \ref{protocoldef:inputvalidation:power} \\
                       & \verb|owners         :| \ref{protocoldef:inputvalidation:owners} \\
                       & \verb|groups         :| The key for the array, must be present \\ \hline
                       & \verb|coordinates    :| \ref{protocoldef:inputvalidation:coordinates} \\
                       & \verb|aprs_broadcast :| boolean \\
                       & \verb|enabled        :| boolean \\
                       & \verb|auth_key       :| \ref{protocoldef:inputvalidation:authkey} \\
                       & \verb|antenna        :| The key for the array, must be present \\
                       & \verb|type           :| \ref{protocoldef:inputvalidation:antennatype} \\
                       & \verb|gain           :| \ref{protocoldef:inputvalidation:antennagain}\\
                       & \verb|direction      :| \ref{protocoldef:inputvalidation:antennadirection}\\
                       & \verb|agl            :| \ref{protocoldef:inputvalidation:antennaagl}\\
                       & \verb|transmit_rubrics_format :| Array with possible content "SKYPER" and "PLAIN"\\
                       & \verb|direction      :| \ref{protocoldef:inputvalidation:antennadirection}\\ \hline


  \end{tabular}
\end{table}
\FloatBarrier

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example content to add transmitter db0wa
\begin{lstlisting}
{
  "_id": "db0wa",
  "usage": "widerange",
  "timeslots": [
    true,
    true,
    false,
    true,
    true,
    false,
    true,
    true,
    false,
    false,
    true,
    true,
    false,
    true,
    true,
    false
  ],
  "power": 20,
  "owners": [
    "dh3wr"
  ],
  "groups": [
    "dl.nw.koeln.aachen"
  ],
  "emergency_power": {
    "available": true,
    "infinite": false,
    "duration": 7200
  },
  "coordinates": [
    50.71613,
    6.165481
  ],

  "aprs_broadcast": false,
  "enabled": true,
  "auth_key": "Arj39135jAKS",
  "antenna": {
    "type": "omni",
    "gain": 0,
    "direction": 0,
    "agl": 1
  }
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|created_*| information by database microservice:\\
\begin{lstlisting}
  "_id": "db0wa",
  "usage": "widerange",
  "timeslots": [
    true,
    true,
    false,
    true,
    true,
    false,
    true,
    true,
    false,
    false,
    true,
    true,
    false,
    true,
    true,
    false
  ],
  "power": 20,
  "owners": [
    "dh3wr"
  ],
  "groups": [
    "dl.nw.koeln.aachen"
  ],
  "emergency_power": {
    "available": true,
    "infinite": false,
    "duration": 7200
  },
  "coordinates": [
    50.71613,
    6.165481
  ],

  "aprs_broadcast": false,
  "enabled": true,
  "auth_key": "Arj39135jAKS",
  "antenna": {
    "type": "omni",
    "gain": 0,
    "direction": 0,
    "agl": 1
  },
  "created_on": "2018-07-08T11:50:02.168325Z",
  "created_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\newpage
\subsubsection{PUT /transmitters - Edit existing transmitter}
Edit is differentiated from create by the presence of the \colorbox{red}{\texttt{\_rev}} field.

\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Edit the existing transmitter <transmittername>.\\ \hline
    Permission         & \verb|transmitter.update/<transmittername>| \\ \hline
    Mapping to CouchDB & \verb|PUT /transmitters/<transmittername>|\\ \hline
    Mandatory fields   & \verb|_id, _rev| (\verb|_rev| has to be obtained as in \ref{protocoldef:microservicesapi:database:gettransmitter/transmittername})\\ \hline
    Optional fields    & \verb|usage, timeslots, power, owners, groups,| \\
                       & \verb|coordinates, aprs_broadcast, enabled, auth_key|\\
                       & \verb|antenna, type, gain, direction, agl| (minimum one, arrays complete) \\ \hline
    Field validation   & \verb|_id            :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|_rev           :| Let CouchDB decide, as the entry is already present. \\
                       & \verb|usage          :| \ref{protocoldef:inputvalidation:usage}\\
                       & \verb|timeslots      :| \ref{protocoldef:inputvalidation:timeslots}\\
                       & \verb|power          :| \ref{protocoldef:inputvalidation:power} \\
                       & \verb|owners         :| \ref{protocoldef:inputvalidation:owners} \\
                       & \verb|groups         :| The key for the array, must be present \\ \hline
                       & \verb|coordinates    :| \ref{protocoldef:inputvalidation:coordinates} \\
                       & \verb|aprs_broadcast :| boolean \\
                       & \verb|enabled        :| boolean \\
                       & \verb|auth_key       :| \ref{protocoldef:inputvalidation:authkey} \\
                       & \verb|antenna        :| The key for the array, must be present \\
                       & \verb|type           :| \ref{protocoldef:inputvalidation:antennatype} \\
                       & \verb|gain           :| \ref{protocoldef:inputvalidation:antennagain}\\
                       & \verb|direction      :| \ref{protocoldef:inputvalidation:antennadirection}\\
                       & \verb|agl            :| \ref{protocoldef:inputvalidation:antennaagl}\\ \hline
  \end{tabular}
\end{table}
\FloatBarrier

\textbf{Auth response: \texttt{true}:}
User to Database-Service: Example to edit usage of transmitter db0wa:
\begin{lstlisting}
{
  "_id": "db0wa",
  "_rev": "1-44182aeb25815b19babe1c0a6bb95e68",
  "usage": "widerange"
}
\end{lstlisting}

Mapping to CouchDB with adding \verb|updated_*| information by database microservice:\\
\begin{lstlisting}
{
  "_id": "dl1abc",
  "_rev": "1-44182aeb25815b19babe1c0a6bb95e68",
  "updated_on": "2018-07-08T11:50:02.168325Z",
  "updated_by": <username from basic-auth>
}
\end{lstlisting}

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\todo{Is an active connection reset to that transmitter necessary? If the Authkey changes, an already established connection will keep working? And what about timeslot changes? They have to be applied immediately to the transmitter.}

\newpage
\subsubsection{DELETE /transmitters/<transmittername>?rev=<rev>}
\begin{table}[htbp]
  \begin{tabular}{|l|p{12cm}|} \hline
    Item               & Description  \\ \hline \hline
    Description        & Delete transmitter <transmittername>\\ \hline
    Permission         & \verb|transmitter.delete/<transmittername>| \\ \hline
    Mapping to CouchDB & \verb|DELETE /transmitter/<transmitername>?rev=<rev>|\\ \hline
    Mandatory fields   & \verb|rev| as parameter (\verb|rev| has to be obtained as in  \ref{protocoldef:microservicesapi:database:gettransmitter/transmittername})\\ \hline
  \end{tabular}
\end{table}

\textbf{Auth response: \texttt{true}:}\\
Transparent forwarding.

\textbf{Auth response: \texttt{false} or \texttt{limited}:}\\
Send \verb|403 Forbidden|.

\todo{Is an active connection reset to that transmitter necessary?}

\newpage
\subsection{Call Service}

\subsubsection{GET /calls}
Returns the last 100 calls with all details.

\subsubsection{GET /calls?limit=<number>}

Returns the last <number> of calls with all details. If <number> is higher than the available calls, just return all available calls.

\subsubsection{GET /calls/\_view/byDate}
With GET parameters:

\begin{verbatim}
GET /calls/_view/byDate?startkey="<startddate">&endkey="<enddate>"
\end{verbatim}

Returns the calls made within the specified time span with all details. If there are no calls stored in the specified time span, return empty JSON.

\subsubsection{GET /calls/\_view/byIssuer}
\begin{verbatim}
GET /calls/_view/byIssuer?key="dh3wr"
\end{verbatim}

Returns all the calls issued from callsign dh3wr with all details. If there are no calls stored with in the specified time span, return empty JSON. (The microservice has to transfrom the request into \textit{startkey="dh3wr"\&endkey="dh3wr"} to the CouchDB GET request by itself.)

\subsubsection{GET /calls/\_view/byRecipient}
\begin{verbatim}
GET /calls/_view/byRecipient?key="dh3wr"
\end{verbatim}

Returns all the calls with recipient callsign dh3wr with all details. If there are no calls stored in the specified time span, return empty JSON. (The microservice has to transfrom the request into \textit{startkey="dh3wr"\&endkey="dh3wr"} to the CouchDB GET request by itself.)

\todo{Any combination of the given filter method shall be possible. It this possible?}

\subsubsection{GET /calls/\_view/pending}

Return all details of pending calls, that are not transmitted by at least one transmitter.

\subsubsection{GET /calls/\_view/pending\_all}
Return all details of pending calls, that are not transmitted by all designated transmitters.

\subsubsection{POST /call}
Insert call to the system. Send in POST content:
\begin{lstlisting}
{
  "subscriber": ["dh3wr",...],
  "subscriber\_groups": ["dl.ov-g01",...]
  "priority" : 1 to 5,
  "message": "This is an example call",
  "transmitter_groups": ["dl-all","on-all"]
}
\end{lstlisting}

\subsection{Rubric Service}

\subsubsection{GET /news}
Returns an array of all rubrics and their content in JSON format.
\todo{zu bedenken}

\subsubsection{GET /news/\_view/byRubric}
\begin{verbatim}
GET /news/_view/byRubric?startkey="metar-dl"&endkey="metar-dl"
\end{verbatim}

Returns just the content of <rubricname> content in JSON format.

\subsubsection{GET /news/\_view/byRubric/message\_no>}
Returns just the content of <rubricname> content and message number <message\_no> in JSON format.

\subsubsection{PUT /news/<rubricname>}
Add content to rubric <rubricname> on the first message slot and move the existing message one to the end. The 10th. entry will be lost. An automated resend of all rubric content slots will be necessary.

\subsubsection{PUT /news/<rubricname>/<message\_no>}
Add or override the content of rubric <rubricname> on the message slot <message\_no>. An automated resend of just this message slot will be necessary.

\subsubsection{DELETE /news/<rubricname>?rev=}
Delete all content in rubric <rubricname>. The content will be still on Skypers that have received it before, but it will not be transmitted periodically any more. No dependency check necessary.

\subsubsection{DELETE /news/<rubricname>/<message\_no>?rev=}
Delete the content in rubric <rubricname> with message slot <message\_no>. The content will be still on Skypers that have received it before, but it will not be transmitted periodically any more. No dependency check necessary.

\subsection{Transmitter Service}

\subsubsection{GET /transmitters}
Return all transmitters with all details in JSON format.

\textbf{limited}: \verb|_id, _rev, usage, timeslots, power, owners, groups, emergency_power, coordinates, aprs_broadcast, enabled, auth_key, antenna, created_on, created_by, changed_on, changed_by| and sub-JSON-nodes of these keys.

\subsubsection{GET /transmitter/<transmittername>}
\label{protocoldef:microservicesapi:database:gettransmitter/transmittername}
Return all details just of transmitter <transmittername>.


\textbf{limited}: \verb|_id, _rev, usage, timeslots, power, owners, groups, emergency_power, coordinates, aprs_broadcast, enabled, auth_key, antenna, created_on, created_by, changed_on, changed_by| and sub-JSON-nodes of these keys.

\subsubsection{POST /transmitters/\_bootstrap}
\label{protcoldef:transmitters:bootstrap}
\texttt{POST /transmitter/bootstrap}
\begin{lstlisting}
{
  "callsign": "db0avr",
  "auth_key": "<secretInCleartext>",
  "software": {
    "name": "UniPager",
    "version": "1.0.2"
  }
}
\end{lstlisting}

\textbf{Answers from the bootstrap REST call}
The application type shall be \verb|application/json|.


\todo{Was mag denn hier der Port sein?}
\texttt{200 OK}
\begin{lstlisting}
{
  "timeslots": [true, true, false, true, ...],
  "nodes": [
    {
      "host": "node1.ampr.org",
      "port": 4000,
      "reachable": true,
      "last_seen": "2018-07-03T07:43:52.783611Z",
      "response_time": 42
    }
  ]
}
\end{lstlisting}

\texttt{423 Locked}
\begin{lstlisting}
{
  "error": "Transmitter temporarily disabled by configuration."
}
\end{lstlisting}

\texttt{423 Locked}
\begin{lstlisting}
{
  "error": "Transmitter software type not allowed due to serious bug."
}
\end{lstlisting}


\subsubsection{POST /transmitters/\_heartbeat}
\texttt{POST /transmitter/heartbeat}
\begin{lstlisting}
{
  "callsign": "db0avr",
  "auth_key": "<secretInCleartext>",
  "ntp_synced": true
}
\end{lstlisting}

\textbf{Answers from the heartbeat REST call}
The application type shall be \verb|application/json|.

\texttt{200 OK}
\begin{lstlisting}
{
  "status": "ok"
}
\end{lstlisting}

If network wants to assign new timeslots without disconnecting (for dynamic timeslots)

\texttt{200 OK}
\begin{lstlisting}
{
  "status": "ok",
  "timeslots": [true, true, false, ...],
  "valid_from": "2018-07-03T08:00:52.786458Z"
}
\end{lstlisting}

If network wants to initiate handover to other node

\texttt{503 Service unavailable}
\begin{lstlisting}
{
  "error": "Node not available, switch to other node."
}
\end{lstlisting}


\subsection{Cluster Service}

\subsubsection{POST /cluster/discovery}


\subsection{Telemetry Service}

\subsubsection{GET /telemetry/transmitters}
Return the stored telemetry \textbf{summary} values for all transmitters.

\subsubsection{GET /telemetry/transmitters/<transmittername>}
Return all the stored telemetry values for transmitter <transmittername>.

\subsubsection{GET /telemetry/nodes}
Return the stored telemetry \textbf{summary} values for all nodes.

\subsubsection{GET /telemetry/nodes/<nodesname>}
Return all the stored telemetry values for node <nodename>.

\subsubsection{WS /telemetry}
See \hyperref[protocoldef:websocketapi]{the section for Websocket API}.


\subsection{Database Changes Service}

\subsubsection{WS /changes}
See \hyperref[protcoldef:websocketapi:databasechanges]{the section for Websocket API on database changes}.

\subsection{Status Service}
The purpose of the status service is to provide a short overview of the DAPNET network and the microservices.

\subsubsection{GET /status/nodes}
No authentication required.

Answer:
\texttt{200 OK}
\begin{lstlisting}
{
  "nodes": [
    {
      "host": "node1.ampr.org",
      "port": 4000,
      "reachable": true,
      "last_seen": "2018-07-03T07:43:52.783611Z",
      "response_time": 42
    }
  ],
  "connections": {
    "rabbitmq": true,
    "couchdb": true,
    "hamcloud": true,
  },
  "hamcloud_node": false,
  "general_health": true
}
\end{lstlisting}
\todo{What is "port"?}

\subsubsection{GET /status/node/<nodename>}
No authentication required.

Answer:
\texttt{200 OK}
\begin{lstlisting}
{
  "host": "node1.ampr.org",
  "port": 4000,
  "reachable": true,
  "last_seen": "2018-07-03T07:43:52.783611Z",
  "response_time": 42,
  "connections": {
    "rabbitmq": true,
    "couchdb": true,
    "hamcloud": true,
  },
  "hamcloud_node": false,
  "general_health": true
}
\end{lstlisting}
\todo{What is "port"?}


\subsubsection{GET /status}
Get status of this node.
\texttt{200 OK}
\begin{lstlisting}
{
  "good_health" : true,
  "version" : "1.2.3"
  "microservices\_running" : {
    "database" : true,
    "call" : true,
    "rubric" : true,
    "transmitter" : true,
    "cluster" : true,
    "telemetry" : true,
    "database-changes" : true,
    "statistics" : true,
    "rabbitmq" : true,
    "thirdparty" : true
  }
}
\end{lstlisting}

\subsubsection{GET /status/<service\_name>}
List of valid values for \textit{service\_name}:

database-service\\
call-service\\
rubric-service\\
transmitter-service\\
cluster-service\\
telemetry-service\\
database-changes-service\\
statistics-service\\
rabbitmq-service\\


\texttt{200 OK}
\begin{lstlisting}
<Status output from service itself>
\end{lstlisting}


\subsection{Statistics Service}

\subsubsection{GET /statistics}
No authentication required.

Answer:
\texttt{200 OK}
\begin{lstlisting}
{
  "users" : 1234,
  "transmitters": {
    "personal": {
      "online": 13
      "total": 34
    },
    "widerage": {
      "online": 53,
      "total": 97
    }
  }
  "nodes": {
    "online": 10,
    "total": 19
  },
  "processed_calls": 1234,
  "processed_rubric_content_changes": 234
}
\end{lstlisting}

\todo{On the calls and rubric content changes: Always increasing counter link traffic on network device or reset at 00:00 am?}

\newpage
\subsection{Auth Service}
\label{protocoldef:Auth}
The auth service provides authentication information to all other services. It works on the CouchDB and reads information from there.

\subsubsection{Password hashing}
In version 1, the used hashing algorithm was \verb|PBKDF2WithHmacSHA1|. In DAPNET 2, the preferred algorithm is \verb|BCrypt|. In order not to send emails to every already registered user to update her/his password, both hashing algorithms are supported by the Auth Service. Anyway, as soon as a user sends its credentials and in the database, still the \verb|PBKDF\ hash is stored, it is updated with the corresponding hash in \verb|BCrypt| format.\\
The format of the hash can be distinguished by the \verb|$2a$, $2b$| or \verb|$2y$|-Prefix. With this method, the transition happens transparently regarding the user.

\subsubsection{Role definition}
The following roles are available:
\begin{table}[htbp!]
\label{tab:protocoldef:permissionmatrix:roledefinition}
  \begin{tabular}{|l|p{11cm}|} \hline
    Name                  & Description \\ \hline \hline
    \verb|user|           & This is a normal user with the possibility of being owner of a subscriber association and transmitters. \\ \hline
    \verb|support|        & Trustworthy volunteer that is working on the user support, e.g. the ticket system. Can manage user, transmitter, subscriber and rubric settings. \\ \hline
    \verb|admin|          & Can do everything, especially create new nodes. \\ \hline
    \verb|thirdparty.<X>| & A machine interface user being able to subscribe to the third party MQTT topics for service <X>. Examples are APRS or Brandmeister. \\ \hline
    \verb|guest|          & Any other request making entity. \\ \hline
  \end{tabular}
  \caption{Role definition}
\end{table}
\FloatBarrier

A user can be part of multiple roles. The Auth service as to check for each permission, if at least one of the roles allows it. Otherwise it is denied.

\subsubsection{Permission definition}
The following permissions are available:

\begin{table}[htbp!]
\label{tab:protocoldef:permissionmatrix:permissiondefinition}
  \begin{tabular}{|l|p{11cm}|} \hline
    Name            & Description \\ \hline \hline
    \verb|all|      & All data access and modification allowed.  \\ \hline
    \verb|none|     & Data access and modification forbidden. \\ \hline
    \verb|if_owner| & Data modification allowed, if asking username is in \verb|owners| list of the entity. \\ \hline
    \verb|limited|  & Data access is restricted. The consuming service has to define what that means in detail. \\ \hline
  \end{tabular}
  \caption{Permission definition}
\end{table}
\FloatBarrier


\subsubsection{Permission naming definition}
The name of the permission has the following significance:
\begin{table}[htbp!]
\label{tab:protocoldef:permissionmatrix:permissionnamingdefinition}
  \begin{tabular}{|l|p{11cm}|} \hline
    Name                      & Description \\ \hline \hline
    \verb|*.list|             & Get an array of all \_ids or further summary data. Used for selections by users. \\
    \hline
    \verb|*.read|             & Get one or many documents in complete or limited version. A white list defined in the corresponding section of this document is given for the limited case. \\ \hline
    \verb|*.create|           & Create a new document. \\ \hline
    \verb|*.update|           & Modify an existing document. \\ \hline
    \verb|*.delete|           & Delete an existing document. \\ \hline
    \verb|user.change_role|   & Change the \verb|roles| array of a user's entry. \\ \hline
  \end{tabular}
  \caption{Permission naming definition}
\end{table}
\FloatBarrier

\subsubsection{Permission matrix}
\label{protocoldef:permissionmatrix}
The following table defines for each role which actions are permitted.

\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:usersdb}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action                  & admin & support & user      & guest & thirdparty.<X> \\ \hline \hline
    \verb|user.list|        & all   & all     & all       & none  & all       \\ \hline
    \verb|user.read|        & all   & all     & limited   & none  & none \\ \hline
    \verb|user.create|      & all   & all     & none      & none  & none      \\ \hline
    \verb|user.update|      & all   & all     & if\_owner & none  & if\_owner \\ \hline
    \verb|user.delete|      & all   & all     & if\_owner & none  & if\_owner \\ \hline
    \verb|user.change_role| & all   & none    & none      & none  & none      \\ \hline
  \end{tabular}
  \caption{Role's permissions for users database}
\end{table}

\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:nodesdb}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action             & admin & support & user    & guest   & thirdparty.<X> \\ \hline \hline
    \verb|node.list|   & all   & all     & limited & limited & all  \\ \hline
    \verb|node.read|   & all   & all     & limited & limited & all  \\ \hline
    \verb|node.create| & all   & all     & none    & none    & none \\ \hline
    \verb|node.update| & all   & all     & none    & none    & none \\ \hline
    \verb|node.delete| & all   & all     & none    & none    & none \\ \hline
  \end{tabular}
  \caption{Role's permissions for nodes database}
\end{table}

\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:rubricdb}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action               & admin & support & user & guest & thirdparty.<X> \\ \hline \hline
    \verb|rubric.list|   & all   & all     & all  & none  & all  \\ \hline
    \verb|rubric.read|   & all   & all     & all  & none  & all  \\ \hline
    \verb|rubric.create| & all   & all     & none & none  & none \\ \hline
    \verb|rubric.update| & all   & all     & none & none  & none \\ \hline
    \verb|rubric.delete| & all   & all     & none & none  & none \\ \hline
  \end{tabular}
  \caption{Role's permissions for rubrics database}
\end{table}

\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:newsdb}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action             & admin & support & user      & guest & thirdparty.<X> \\ \hline \hline
    \verb|news.read|   & all   & all     & all       & none  & all       \\ \hline
    \verb|news.create| & all   & all     & if\_owner & none  & if\_owner \\ \hline
    \verb|news.update| & all   & all     & if\_owner & none  & if\_owner \\ \hline
    \verb|news.delete| & all   & all     & if\_owner & none  & if\_owner \\ \hline
  \end{tabular}
  \caption{Role's permissions for news database}
\end{table}


\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:subscribersdb}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action                        & admin & support & user      & guest & thirdparty.<X> \\ \hline \hline
    \verb|subscriber.list|        & all   & all     & all       & none  & all            \\ \hline
    \verb|subscriber.read|        & all   & all     & limited   & none  & limited        \\ \hline
    \verb|subscriber.create|      & all   & all     & none      & none  & none           \\ \hline
    \verb|subscriber.update|      & all   & all     & if\_owner & none  & if\_owner      \\ \hline
    \verb|subscriber.delete|      & all   & all     & if\_owner & none  & if\_owner      \\ \hline
    \verb|subscriber_groups.list| & all   & all     & all       & none  & all            \\ \hline
  \end{tabular}
  \caption{Role's permissions for subscribers database}
\end{table}



\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:transmittersdb}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action                         & admin & support & user      & guest    & thirdparty.<X> \\ \hline \hline
    \verb|transmitter.list|        & all   & all     & all       & limited  & all       \\ \hline
    \verb|transmitter.read|        & all   & all     & limited   & none     & limited   \\ \hline
    \verb|transmitter.create|      & all   & all     & none      & none     & none      \\ \hline
    \verb|transmitter.update|      & all   & all     & if\_owner & none     & if\_owner \\ \hline
    \verb|transmitter.delete|      & all   & all     & if\_owner & none     & if\_owner \\ \hline \hline
    \verb|transmitter_groups.list| & all   & all     & all       & none     & all       \\ \hline
  \end{tabular}
  \caption{Role's permissions for transmitters database}
\end{table}



\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:transmitters}
  \begin{tabular}{|l|p{7cm}|} \hline
    action                                & comment \\ \hline \hline
    \verb|transmitter.new_conn_post|      & If transmitter credentials are ok\\ \hline
    \verb|transmitter.rabbitmq.subscribe| & If transmitter credentials are ok, for both RX of messages and TX of telemetry \\ \hline
  \end{tabular}
  \caption{Role's permissions for transmitters}
\end{table}



\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:websocket}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action                              & admin & support & user    & guest & thirdparty.<X> \\ \hline \hline
    \verb|ws.telemetry.subscribe|       & all   & all     & all     & all   & all    \\ \hline
    \verb|ws.database_change.subscribe| & all   & all     & limited & none  & limited \\ \hline
  \end{tabular}
  \caption{Role's permissions for websocket}
\textbf{limited}: Just same content as permitted over http. Websocket authentication like in unipager.
\end{table}

\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:statusandstats}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action                 & admin & support & user & guest & thirdparty.<X> \\ \hline \hline
    \verb|status.read|     & all   & all     & all  & all   & all    \\ \hline
    \verb|statistics.read| & all   & all     & all  & all   & all \\ \hline
  \end{tabular}
  \caption{Role's permissions for status and statistics}
\end{table}

\begin{table}[htbp]
\label{tab:protocoldef:permissionmatrix:mqtt}
  \begin{tabular}{|l|c|c|c|c|c|} \hline
    action                                   & admin & support & user & guest & thirdparty.<X> \\ \hline \hline
    \verb|thirdparty.subscribe.aprs|         & all   & none    & none  & none & if\_<X>=aprs         \\ \hline
    \verb|thirdparty.subscribe.brandmeister| & all   & none    & none  & none & if\_<X>=brandmeister \\ \hline
  \end{tabular}
  \caption{Role's permissions for MQTT subscription}
\end{table}

\newpage
\subsubsection{Auth API definition}
\label{protocoldef:auth:api}
The following table states all Auth Service API calls and their description. The POST request has to come always with a POST content of:
\begin{lstlisting}
 {"username": "<asking_user>", "password": "<asking_user's_password>"}
\end{lstlisting}

There are two endpoints on the Auth service. One for overview of permissions and one explicitly answering, if a permission is granted.

\textbf{POST /auth/users/login}\\
This returns an detailed overview of all permissions of the user referred in the POST content. If a permission is not listed, it's implicitly \verb|none|. Example output:
\begin{lstlisting}
{
  "user": {
    "roles": [
      "admin",
      "support",
      "user"
    ],
    "enabled": true,
    "email": "mailmenot@dl2ic.de",
    "created_on":"2018-07-08T11:50:02.168325Z",
    "created_by": "dh3wr",
    "_rev": "4-3ebbe52b3da83a2a6c1f8093efebdc07",
    "_id": "dl2ic"
  },
  "permissions": {
    "user.update": "all",
    "user.read": "all",
    "user.list": "all",
    "user.delete": "all",
    "user.create": "all",
    "user.change\_role": "all",
    "transmitter\_groups.list": "all",
    "transmitter.update": "all",
    "transmitter.read": "all",
    "transmitter.list": "all",
    "transmitter.delete": "all",
    "transmitter.create": "all",
    "subscriber\_groups.list": "all",
    "subscriber.update": "all",
    "subscriber.read": "all",
    "subscriber.list": "all",
    "subscriber.delete": "all",
    "subscriber.create": "all",
    "rubric.update": "all",
    "rubric.read": "all",
    "rubric.list": "all",
    "rubric.delete": "all",
    "rubric.create": "all",
    "node.update": "all",
    "node.read": "all",
    "node.list": "all",
    "node.delete": "all",
    "node.create": "all",
    "news.update": "all",
    "news.read": "all",
    "news.delete": "all",
    "news.create": "all"
  }
}
\end{lstlisting}

\textbf{POST /auth/users/permissions/<permission>/<entity>}\\
This is a explicit query endpoint for a specific <permission> as listed in section \ref{protocoldef:permissionmatrix}. The entity against the permission is applied is <entity>. Ownership \text{bf} is considered in this case by the Auth Service.

\textbf{POST /auth/users/permissions/<service>.read}\\
This is a explicit query endpoint for a <service>.read permission grant to get one or many documents. Ownership is \textbf{NOT} considered in this case. The consuming service has to take care of adequate data handling.


There are three possible answers:

\textbf{Access is granted completely:}
\begin{lstlisting}
{ "access": true }
\end{lstlisting}

\textbf{Access is forbidden completely:}
\begin{lstlisting}
{ "access": false }
\end{lstlisting}

\textbf{Access granted, but limited to a subset of data:}
\begin{lstlisting}
{
  "access": false,
  "limited": true
}
\end{lstlisting}

\colorbox{red}{If the \texttt{limited} key is not present, the access is still forbidden.}\\

\textbf{GET /auth/users/roles}\\
A JSON array of available roles can be obtained without authentication by.\\
Example output:
\begin{lstlisting}
["user","support","admin","thirdparty.brandmeister","thirdparty.aprs"]
\end{lstlisting}

\newpage
\subsubsection{Auth call reference list}
In order to shorten the table, the abbreviation \textbf{/a/u/p} is used to represent\\
\textbf{/auth/users/permission}.\\

The value in \verb|< >| is always the resource to be accessed.\\

\begin{table}[htbp]
\label{tab:protocoldef:auth:API}
  \begin{tabular}{|l|l|l|} \hline
    \textbf{Auth REST endpoint}                    & \textbf{Referring to}                & \textbf{Section}\\ \hline \hline
    \verb|POST /a/u/p/user.list|                   & \verb|GET    /users/_usernames|      &
        \ref{protocoldef:microservicesapi:database:getusers/_usernames} \\ \hline
    \verb|POST /a/u/p/user.read/<username>|        & \verb|GET    /users/<username>|      &
        \ref{protocoldef:microservicesapi:database:getusers/username} \\ \hline
    \verb|POST /a/u/p/user.read|                   & \verb|GET    /users|             &
        \ref{protocoldef:microservicesapi:database:getusers} \\ \hline
    \verb|POST /a/u/p/user.create|                 & \verb|PUT    /users|                 &
        \ref{protocoldef:microservicesapi:database:putusers/username_create} \\ \hline
    \verb|POST /a/u/p/user.update/<username>|      & \verb|PUT    /users|                 &
        \ref{protocoldef:microservicesapi:database:putusers/username_update} \\ \hline
    \verb|POST /a/u/p/user.delete/<username>|      & \verb|DELETE /users/<username>?rev=| &
        \ref{protocoldef:microservicesapi:database:deleteusers} \\ \hline
    \verb|POST /a/u/p/user.change_role/<username>| & \verb|PUT    /users|                 &
        \ref{protocoldef:microservicesapi:database:putusers/username_update} \\ \hline
    \hline
    \verb|POST /a/u/p/transmitter.list|               & \verb|GET    /transmitters/_transmitternames| & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter.read/<txname>|      & \verb|GET    /transmitters/<txname>|          & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter.read|               & \verb|GET    /transmitters[?*]|               & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter.create|             & \verb|PUT    /transmitters|                   & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter.update/<txname>|    & \verb|PUT    /transmitters|                   & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter.delete/<txname>|    & \verb|DELETE /transmitters/<txname>?rev=|     & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter_groups.list|        & \verb|GET    /transmitters/_groups|           & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter.new_conn_post|      & \verb|POST   /transmitters/bootstrap|        & \ref{pr} \\ \hline
    \verb|POST /a/u/p/transmitter.rabbitmq.subscribe| & \textit{RabbitMQ Auth}                        & \ref{pr} \\ \hline
    \hline
    \verb|POST /a/u/p/subscriber.list|               & \verb|GET    /subscribers/_subscribernames| & \ref{pr} \\ \hline
    \verb|POST /a/u/p/subscriber.read/<subscname>|   & \verb|GET    /subscribers/<subscname>|      & \ref{pr} \\ \hline
    \verb|POST /a/u/p/subscriber.read|               & \verb|GET    /subscribers[?*]|              & \ref{pr} \\ \hline
    \verb|POST /a/u/p/subscriber.create|             & \verb|PUT    /subscribers|                  & \ref{pr} \\ \hline
    \verb|POST /a/u/p/subscriber.update/<subscname>| & \verb|PUT    /subscribers|                  & \ref{pr} \\ \hline
    \verb|POST /a/u/p/subscriber.delete/<subcname>|  & \verb|DELETE /subscribers/<subscname>?rev=| & \ref{pr} \\ \hline
    \verb|POST /a/u/p/subscriber_groups.list|        & \verb|GET    /subscribers/_groups|          & \ref{pr} \\ \hline
    \hline
    \verb|POST /a/u/p/node.list|              & \verb|GET    /nodes/_nodenames|        &
        \ref{protocoldef:microservicesapi:database:getnodes/_nodenames} \\
                                              & \verb|GET /nodes/_nodenamedescription| &
        \ref{protocoldef:microservicesapi:database:getnodes/_nodenamesdescription} \\  \hline
    \verb|POST /a/u/p/node.read/<nodename>|   & \verb|GET    /nodes/<nodename>|        &
        \ref{protocoldef:microservicesapi:database:getnodes/nodename} \\               \hline
    \verb|POST /a/u/p/node.read|              & \verb|GET    /nodes[?*]|               &
        \ref{protocoldef:microservicesapi:database:getnodes} \\                        \hline
    \verb|POST /a/u/p/node.create|            & \verb|PUT    /nodes|                   &
        \ref{protocoldef:microservicesapi:database:putnodes/node_create} \\            \hline
    \verb|POST /a/u/p/node.update/<nodename>| & \verb|PUT    /nodes|                   &
        \ref{protocoldef:microservicesapi:database:putnodes/node_update} \\            \hline
    \verb|POST /a/u/p/node.delete/<nodename>| & \verb|DELETE /nodes/<nodename>?rev=|   &
        \ref{protocoldef:microservicesapi:database:deletenode} \\                \hline
    \hline
    \verb|POST /a/u/p/rubric.list|                & \verb|GET    /rubrics/_rubricnames|       &
        \ref{protocoldef:microservicesapi:database:getrubrics/_rubricnames} \\ \hline
    \verb|POST /a/u/p/rubric.read/<rubricname>|   & \verb|GET    /rubrics/<rubricsame>|       &
        \ref{protocoldef:microservicesapi:database:getrubrics/rubricname} \\ \hline
    \verb|POST /a/u/p/rubric.read|                & \verb|GET    /rubrics[?*]|                &
        \ref{protocoldef:microservicesapi:database:getrubrics} \\ \hline
    \verb|POST /a/u/p/rubric.create|              & \verb|PUT    /rubrics|                    &
        \ref{protocoldef:microservicesapi:database:putrubrics/rubrics_create} \\ \hline
    \verb|POST /a/u/p/rubric.update/<rubricname>| & \verb|PUT    /rubrics|                    &
        \ref{protocoldef:microservicesapi:database:putrubrics/rubrics_update} \\ \hline
    \verb|POST /a/u/p/rubric.delete/<rubricname>| & \verb|DELETE /rubrics/<rubricsname>?rev=| &
        \ref{protocoldef:microservicesapi:database:deleterubric} \\ \hline
    \hline
    \verb|POST /a/u/p/news.read|                & \verb|GET    /news[?*]|                        & \ref{pr} \\ \hline
    \verb|POST /a/u/p/news.create|              & \verb|PUT    /news|                            & \ref{pr} \\ \hline
    \verb|POST /a/u/p/news.update/<rubricname>| & \verb|PUT    /news/<rubricname>|               & \ref{pr} \\ \hline
    \verb|POST /a/u/p/news.delete/<rubricname>| & \verb|DELETE /news/<rubricname>?rev=|          & \ref{pr} \\ \hline
    \verb|POST /a/u/p/news.delete/<rubricname>| & \verb|DELETE /news/<rubricname>/<msg_no>?rev=| & \ref{pr} \\ \hline
    \hline
    \verb|POST /a/u/p/ws.telemetry.subscribe|       & \verb|WS /telemetry/*| & \ref{pr} \\
    \verb|POST /a/u/p/ws.database_change.subscribe| & \verb|WS /changes/*|   & \ref{pr} \\ \hline
    \hline
    \verb|POST /a/u/p/status.read|     & \verb|GET    /status/*|     & \ref{pr} \\ \hline
    \verb|POST /a/u/p/statistics.read| & \verb|GET    /statistics/*| & \ref{pr} \\ \hline
    \hline
    \verb|POST /a/u/p/thirdparty.subscribe.<service>| & \textit{MQTT Auth} to subscribe to topic <service> & \ref{pr} \\
    \hline
  \end{tabular}
  \caption{Auth REST API endpoint and references}
\end{table}

\newpage

\subsection{RabbitMQ Service}
\label{protocoldef:RabbitMQ}

\subsubsection{GET /rabbitmq/*}


\section{RabbitMQ}
\label{protocoldef:RabbitMQ}

\subsection{Concept of Calls distribution}
\label{protocoldef:RabbitMQ:calldistribution}

There are 3 exchanges available on each RabbitMQ instance:
\begin{description}
\item[dapnet.calls] Messages shared between all nodes
\item[dapnet.local\_calls] Messages to the local connected transmitters
\item[dapnet.telemetry] Messages containing telemetry from transmitters
\end{description}

The concept of distribution calls is a two-stage approach. On \texttt{dapnet.calls} the calls are distributed among all Nodes forming the DAPNET cluster on an abstract level, where e.g. the resolution from recipient callsigns to their corresponding RICs is not done. Each DAPNET node will listen to this exchange and generate the messages for the locally connected transmitter upon arrival. The selection of transmitters selected by transmitter group tags, explicit transmitter selection or by a polygon coverage area is done on each node. Processed calls will be sent to the \texttt{dapnet.local\_calls} exchange just for the connected transmitters to each node. Receiver hardware equipment dependent encoding will also be done during the processing of the calls from \texttt{dapnet.calls} to \texttt{dapnet.local\_calls} on each calls taking into account the stored hardware type of each pager stored in the CouchDB subscriber. Both personal pagings and rubric related messages are transmitted on the \texttt{dapnet.calls} exchange.


\subsection{Message definition on Exchanges}
\label{protocoldef:RabbitMQ:exchangesdifinition}


Valid Messages are:

\subsubsection{dapnet.calls}
\label{protocoldef:RabbitMQ:dapnet.calls}
The messages to call transfer data between the nodes in an not-processed status are the
\begin{lstlisting}
{
  "id": "016c25fd-70e0-56fe-9d1a-56e80fa20b82",
  "priority": 3,
  "created_by": "dh3wr",
  "created_on": "2018-07-03T06:00:52.786458Z",
  "expires_on": "2018-07-03T08:00:52.786458Z",
  "origin": "db0sda-dc2",
  "data": "Lorem ipsum dolor sit amet",
  "recipients": {
    "subscribers": ["subscriber1", "subscriber2"],
    "subscriber_groups": ["rwth-afu"]
  },
  "distribution" : {
    "transmitters" : ["db0abc"],
    "transmitter_groups": ["dl.nw"],
    "areas": [
      [[50.1, 6.0], [50.1, 7.0], [51.2, 6.0], [51.2, 7.0]]
    ]
  }
}
\end{lstlisting}

\subsubsection{dapnet.local\_calls}
\label{protocoldef:RabbitMQ:dapnet.local_calls}
The RabbitMQ microservice will transform the high-level calls from \texttt{dapnet.calls} into individual messages on texttt{dapnet.local\_calls}. The selection of the transmitter is done by means of the routing key. Besides, the priority is also used in the RabbitMQ queuing to deliver higher priority messages first.

Resolutions to be done are:
\begin{description}
\item["recipients"] Look up the RIC of every pagers in the subscriber and perform corresponding encoding dependent on the pager type.
\item["distribution"] Resolve the \texttt{transmitter\_groups} into an array of corresponding transmitters, resolve the given area to the covering transmitters using the Coverage Microservice \ref{internalprog:microservices:overview:coverage}. The generated list of transmitters is used to send individual messages to each transmitter by means of the routing key. For each of the subscribers pager entries, a separate message will be sent.
\end{description}

The resulting message format is:
\begin{lstlisting}
{
  "id": "016c25fd-70e0-56fe-9d1a-56e80fa20b82",
  "protocol": "pocsag",
  "priority": 3,
  "expires": "2018-07-03T08:00:52.786458Z",
  "origin": "db0sda-dc2",
  "message": {
    "ric": 12345,
    "function": 0...3,
    "type": "alphanum" | "numeric",
    "speed": 1200,
    "data": "Lorem ipsum dolor sit amet",
  }
}
\end{lstlisting}


\subsection{Telemetry}
On the telemetry exchange, all transmitters and nodes publish their telemetry messages. The format the same as in section \ref{protocoldef:telemetrytx} and \ref{protocoldef:telemetrynodes}.

\subsection{MQTT API for third-party consumers}
\label{protocoldef:mqttapi}
In order to allow third-party instances like \href{http://www.aprs-is.net/|APRS}, \href{http://brandmeister.network|Brandmeister} or others to get the emitted calls and rubric contents in a real time event driven way, there is an MQTT API. It is not implemented via a dedicated MQTT broker, but uses the existing RabbitMQ instance (\url{https://www.rabbitmq.com/mqtt.html}. There is no distribution of the messages via this MQTT broker; it is local only. So every node publishes the messages locally on its own.
\todo{check with DL2IC}
Each subscriber has an array of enabled third-party applications. This allow to define the user, if call directed to her/his subscriber shall be also sent to third-party services (see \ref{protocoldef:couchdb:subscribers}.

The currently existing MQTT topics are defined in the CouchDB (see section \ref{protocoldef:couchdb:mqttservicesandsubscribers}). This makes it possible to add more third-party services and authorized users during runtime without the need to update the software.
The valid users to subscribe to the topic are also listed in the same CouchDB database.

The only permitted access for third-party consumers is read. So the subscribe request from a third-party MQTT-Client must use authentication which is checks against the CouchDB data. If correct, read access is granted. Core software has always write access to publish the calls group messages.

The transmitters who are supposed to send out the personal call or the rubric content are published with callsign, geographic location and type of transmitter (widerange or personal). With this generic concept, every third-party application can decide what to do with the content received.

The encoding of the data is UTF-8.

The format of the data published for \textbf{personal paging calls} is
\begin{lstlisting}
{
  "pagingcall" : {
    "srccallsign" : "dl2ic",
    "dstcallsign" : "dh3wr",
    "dstric" : 12354,
    "dstfunction" : 0 .. 3,
    "priority" : 3,
    "message" : "DAPNET 2.0 rocks dear YL/OM"
    "transmitted_by" : [
      {
        "callsign" : "db0abc",
        "lat" : 12.123456,
        "long" : 32.123456,
        "type" : "personal" | "widerange"
      },
      {
        "callsign" : "db0def",
        "lat" : 12.123456,
        "long" : 32.123456,
        "type" : "personal" | "widerange"
      }
    ],
    "timestamp" : "2018-07-03T08:00:52.786458Z"
  }
}
\end{lstlisting}

The format of the data published for \textbf{rubric\_content paging calls} is
\begin{lstlisting}
{
  "rubricmessage" : {
    "message" : ""
    "transmitted_by" : [
      {
        "callsign" : "db0abc",
        "lat" : 12.123456,
        "long" : 32.123456,
        "type" : "PERONAL" | "WIDERANGE"
      },
      {
        "callsign" : "db0def",
        "lat" : 12.123456,
        "long" : 32.123456,
        "type" : "PERONAL" | "WIDERANGE"
      }
    ],
    "timestamp" : "2018-07-03T08:00:52.786458Z"
  }
}
\end{lstlisting}

\section{Telemetry from Transmitters}
\label{protocoldef:telemetrytx}
Telemetry is sent from transmitters to the RabbitMQ exchange
\textbf{dapnet.telemetry} as defined in section \ref{protocoldef:RabbitMQ}. It
is also used in the same way on the websocket API to inform the website and the
app about the telemetry in real-time in section
\ref{protcoldef:websocketapi:telemetrytxsummary} and \ref{protcoldef:websocketapi:telemetrytxdetail}.

This is sent every minute in complete. If there are changes, just a subset is sent.
The name of the transmitter is used as routing key for the message.

\begin{lstlisting}
{
  "onair": true,
  "node": {
    "name": "db0xyz",
    "ip": "44.42.23.8",
    "port": 1234,
    "connected": true,
    "connected_since": "2018-07-03T08:00:52.786458Z"
   },
  "ntp": {
    "synced": true,
    "offset": 124,
    "server": ["134.130.4.1", "12.2.3.2"],
  },
  "messages": {
    "queued": [123, 123, 123, 123, 123, 123],
    "sent": [123, 123, 123 , 123, 123, 123]
  },
  "temperatures": {
    "unit": "C" | "F" | "K",
    "air_inlet": 12.2,
    "air_outlet": 14.2,
    "transmitter": 42.2,
    "power_amplifier": 45.2,
    "cpu": 93.2,
    "power_supply": 32.4,
    "custom": [
      {"value": 12.2, "description": "Aircon Inlet"},
      {"value": 16.2, "description": "Aircon Outlet"},
      {"value": 12.3, "description": "Fridge Next to Programmer"}
    ]
  },
  "power_supply": {
    "on_battery": false,
    "on_emergency_power": false,
    "dc_input_voltage": 12.4,
    "dc_input_current": 3.23
  },
  "rf_output" : {
    "fwd": 12.2,
    "refl" : 12.2,
    "vswr" : 1.2
  },
  "config": {
    "ip": "123.4.3.2",
    "timeslots" : [true, false,...,	false],
    "software": {
      name: "Unipager" | "MMDVM" | "DAPNET-Proxy",
      version: "v1.2.3", | "20180504" | "v2.3.4",
    },
  }
  "hardware": {
    "platform": "Raspberry Pi 3B+"
  },
  "rf_hardware": {
    "c9000": {
      "name" : "C9000 Compact",
      "<pa_dummy>" : {
        "output_power" : 123,
        "port" : "/dev/ttyUSB0"
      }
      "<rpc>": {
        "version" : "XOS/2.23pre"
      }
    },
    "raspager": {
      "name": Raspager",
      "modulation": 13,
      "power": 63,
      "external_pa": false,
      "version": "V2"
    },
    "audio": {
      "name" = "Audio",
      "transmitter": "GM1200" | "T7F" | "GM340" | "FREITEXT",
      "audio_level": 83,
      "tx_delay": 3
    },
    "rfm69": {
      "name" : "RFM69",
      "port": "/dev/ttyUSB0"
    },
    "mmdvm": {
      "name" : "MMDVM",
      "dapnet_exclusive": true
    }
  },
  "proxy" : {
    "status": "connected" | "connecting" | "disconnected"
  }
}
\end{lstlisting}

\section{Telemetry from Nodes}
\label{protocoldef:telemetrynodes}
Telemetry is sent from nodes to the RabbitMQ exchange
\textbf{dapnet.telemetry} as defined in section \ref{protocoldef:RabbitMQ}. It
is also used in the same way on the websocket API to inform the website and the
app about the telemetry in real-time in section
\ref{protcoldef:websocketapi:telemetrynodessummary} and \ref{protcoldef:websocketapi:telemetrynodesdetail}.

This is sent every minute in complete. If there are changes, just a subset is sent.
The name of the nodes is used as routing key for the message.
\begin{lstlisting}
{
  "good_health" : true,
  "microservices" : {
    "database" : {
      "ok" : true,
      "version" : "1.2.3"
    },
    "call" : {
      "ok" : true,
      "version" : "1.2.3"
    },
    "rubric" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "transmitter" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "cluster" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "telemetry" : {
      "ok" : true,
      "version" : "1.2.3"
    },
    "database-changes" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "statistics" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "rabbitmq" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "thirdparty" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
  },
  "connections" : {
    "transmitters" : 123,
    "third_party" : 3
  },
  "system" : {
    "free_disk_space_mb": 1234
    "cpu_utilization": 0.2
    "is_hamcloud" : false
  }
}
\end{lstlisting}

\section{Statistic, Status and Telemetry REST API}
The statistic and telemetry REST API provides up-to-date information regarding the transmitters and the network via REST. This can be used by e.g. grafana to draw nice graphes or nagios plugins.





\subsection{Telemetry from Transmitters}
For authentication refer to section \hyperref[protocoldef:Auth]{Auth Service}.
\texttt{GET /telemetry/transmitters}
Here all stored telemetry from all transmitters is provided.

Answer:
\texttt{200 OK}
See \ref{protocoldef:telemetrytx}\\\\

\texttt{GET /telemetry/transmitters/<transmittername>}
Here all stored telemetry from the specified transmitter is provided.

Answer:
\texttt{200 OK}

See \ref{protocoldef:telemetrytx}\\\\

\texttt{GET /telemetry/transmitters/<transmittername>/<section\_of\_telemetry>}
Here all stored telemetry within the telemetry section from the specified transmitter is provided. Possible sections are 2. Level JSON groups, see \ref{protocoldef:telemetrytx}.

Examples: onair, telemetry, transmitter\_configuration

Answer:
\texttt{200 OK}

See \ref{protocoldef:telemetrytx}

\subsection{Telemetry from Nodes}

\texttt{GET /telemetry/nodes}
Here all stored telemetry from all nodes is provided.

Answer:
\texttt{200 OK}
See \ref{protocoldef:telemetrynodes}\\\\

\texttt{GET /telemetry/nodes/<nodename>}
Here all stored telemetry from the specified node is provided.

Answer:
\texttt{200 OK}

See \ref{protocoldef:telemetrynodes}\\\\


\section{Websocket API}
\label{protocoldef:websocketapi}
The idea is to provide an API for the website and the app to display real-time
information without the need of polling. A websocket server is listing to
websocket connections. Authentication is done by a custom JOSN handshake. The
connection might be encrypted with SSL if using the Internet or plain if using
HAMNET.

The data is taken from the \textbf{dapnet.telemetry} exchange
from the RabbitMQ instance and further other sources if necessary.

For authentication refer to section \hyperref[protocoldef:Auth]{Auth Service}.

Table \ref{tab:protocoldef:websocketapi} lists the main endpoints in the websocket interface:

\begin{table}[htbp]
  \label{tab:protocoldef:websocketapi}
  \begin{center}
    \begin{tabular}{|l|l|} \hline
      Endpoint & Microservice \\ \hline \hline
      \verb|WS /telemetry/transmitters| & Summary data of all TX \\ \hline
      \verb|WS /telemetry/transmitters/<TxName>| & Details for TX <TxName>\\ \hline
      \verb|WS /telemetry/nodes| & Summary data of all Nodes\\ \hline
      \verb|WS /telemetry/nodes/<NodeName>| & Details for Node <NodeName>\\ \hline
      \verb|WS /changes| & Database changes\\ \hline
    \end{tabular}
  \end{center}
  \caption{Websocket endpoints}
\end{table}


\subsection{Telemetry from Transmitters - Summary of all TX}
\label{protcoldef:websocketapi:telemetrytxsummary}
URL: \texttt{ws://FQDN/telemetry/transmitters}\\\\

The data is the same as received from the \textbf{dapnet.telemetry} exchange
from the RabbitMQ instance. It is defined in section
\ref{protocoldef:telemetrytx}.\\
The websocket-Server generates an array of JSON Objects which have the name of the transmitter obtained from the RabbitMQ routing key.\\
The current time slot is also sent in the summary and updated also by its own every time a time slot change happens.

\begin{lstlisting}
{
  "transmitters": [
    "db0abc" : {
      "onair": true,
      "node": {
        "name": "db0xyz",
        "ip": "44.42.23.8",
        "port": 1234,
        "connected": true,
        "connected_since": "2018-07-03T08:00:52.786458Z"
       },
      "ntp": {
        "synced": true
      },
      "messages": {
        "queued": [123, 123, 123, 123, 123, 123],
        "sent": [123, 123, 123 , 123, 123, 123]
      },
      "config": {
        "ip": "123.4.3.2",
        "timeslots" : [true, false,...,	false],
      "software": {
        name: "Unipager" | "MMDVM" | "DAPNET-Proxy",
        version: "v1.2.3", | "20180504" | "v2.3.4"
      },
      "proxy" : {
        "status": "connected" | "connecting" | "disconnected"
      }
    },
    "db0xyz" : {
      "onair": true,
      "node": {
    ....
    }
  ],
  "current_timeslot" : 12
}
\end{lstlisting}

\subsection{Telemetry from Transmitters - Details of Transmitter}
\label{protcoldef:websocketapi:telemetrytxdetail}
URL: \texttt{ws://FQDN/telemetry/transmitters/<transmittername>}\\\\

The data is the same as received from the \textbf{dapnet.telemetry} exchange
from the RabbitMQ instance. It is defined in section
\ref{protocoldef:telemetrytx}.\\
The websocket-Server gives out all the telemetry data from a certain transmitter. The name of the transmitter obtained from the RabbitMQ routing key.

\begin{lstlisting}
{
  "onair": true,
  "node": {
  "ip": "44.42.23.8",
    "port": 1234,
    "connected": true,
    "connected_since": "2018-07-03T08:00:52.786458Z"
  },
  "ntp": {
    "synced": true,
    "offset": 124,
    "server": ["134.130.4.1", "12.2.3.2"],
  },
  "messages": {
    "queued": [123, 123, 123, 123, 123, 123],
    "sent": [123, 123, 123 , 123, 123, 123]
  },
  "temperatures": {
    "unit": "C" | "F" | "K",
    "air_inlet": 12.2,
    "air_outlet": 14.2,
    "transmitter": 42.2,
    "power_amplifier": 45.2,
    "cpu": 93.2,
    "power_supply": 32.4,
    "custom": [
      {"value": 12.2, "description": "Aircon Inlet"},
      {"value": 16.2, "description": "Aircon Outlet"},
      {"value": 12.3, "description": "Fridge Next to Programmer"}
    ]
  },
  "power_supply": {
    "on_battery": false,
    "on_emergency_power": false,
    "dc_input_voltage": 12.4,
    "dc_input_current": 3.23
  },
  "rf_output" : {
    "fwd": 12.2,
    "refl" : 12.2,
    "vswr" : 1.2
  },
  "config": {
    "ip": "123.4.3.2",
    "timeslots" : [true, false,...,	false],
    "software": {
      name: "Unipager" | "MMDVM" | "DAPNET-Proxy",
      version: "v1.2.3", | "20180504" | "v2.3.4",
    },
  }
  "hardware": {
    "platform": "Raspberry Pi 3B+"
  },
  "rf_hardware": {
    "c9000": {
      "name" : "C9000 Compact",
      "<pa_dummy>" : {
        "output_power" : 123,
        "port" : "/dev/ttyUSB0"
      }
      "<rpc>": {
        "version" : "XOS/2.23pre"
      }
    },
    "raspager": {
      "name": Raspager",
      "modulation": 13,
      "power": 63,
      "external_pa": false,
      "version": "V2"
    },
    "audio": {
      "name" = "Audio",
      "transmitter": "GM1200" | "T7F" | "GM340" | "FREITEXT",
      "audio_level": 83,
      "tx_delay": 3
    },
    "rfm69": {
      "name" : "RFM69",
      "port": "/dev/ttyUSB0"
    },
    "mmdvm": {
      "name" : "MMDVM",
      "dapnet_exclusive": true
    }
  },
  "proxy" : {
    "status": "connected" | "connecting" | "disconnected"
  }
}
\end{lstlisting}

\subsection{Telemetry from Nodes - Summary of all Nodes}
\label{protcoldef:websocketapi:telemetrynodessummary}
URL: \texttt{ws://FQDN/telemetry/nodes}\\\\

The websocket-Server generates an array of JSON Objects which have the name of the node obtained from the RabbitMQ routing key.

\begin{lstlisting}
{
  "nodes" : [
    "db0sda" : {
      "good_health" : true,
      "connections" : {
        "transmitters" : 123,
        "third_party" : 3
      },
      "system" : {
        "is_hamcloud" : false
      }
    },
    "hamcloud1" : {
      "good_health" : true,
      "connections" : {
        "transmitters" : 658,
        "third_party" : 25
      },
      "system" : {
        "is_hamcloud" : true
      }
    },
    ....
  ]
}
\end{lstlisting}

\subsection{Telemetry from Transmitters - Details of Node}
\label{protcoldef:websocketapi:telemetrynodesdetail}
URL: \texttt{ws://FQDN/telemetry/nodes/<nodename>}\\\\

The data is the same as received from the \textbf{dapnet.telemetry} exchange
from the RabbitMQ instance. It is defined in section
\ref{protocoldef:telemetrytx}.\\
The websocket-Server gives out all the telemetry data from a certain node. The name of the transmitter obtained from the RabbitMQ routing key.

\begin{lstlisting}
{
  "good_health" : true,
  "microservices" : {
    "database" : {
      "ok" : true,
      "version" : "1.2.3"
    },
    "call" : {
      "ok" : true,
      "version" : "1.2.3"
    },
    "rubric" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "transmitter" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "cluster" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "telemetry" : {
      "ok" : true,
      "version" : "1.2.3"
    },
    "database-changes" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "statistics" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "rabbitmq" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
    "thirdparty" :  {
      "ok" : true,
      "version" : "1.2.3"
    },
  },
  "connections" : {
    "transmitters" : 123,
    "third_party" : 3
  },
  "system" : {
    "free_disk_space_mb": 1234
    "cpu_utilization": 0.2
    "is_hamcloud" : false
  }
}
\end{lstlisting}

\subsection{Database Changes}
\label{protcoldef:websocketapi:databasechanges}
URL: \texttt{ws://FQDN/changes}\\

To inform the website or the app about changes in the CouchDB database, the
websocket microservice keeps a connection to the local CouchDB API and receives
a stream of updated to the database. As there may be data in the changes that
are confidential, the stream is parsed and sent out in a reduced form to the
websocket client. Further information:
\url{http://docs.couchdb.org/en/2.0.0/api/database/changes.html}

The format of the updates is:

\todo{define/review format}

\subsubsection{Transmitter related}
\texttt{New transmitter added}

\begin{lstlisting}
{
  "type": "transmitter",
  "action" : "added",
  "name": "db0abc",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{Existing transmitter changed}
\begin{lstlisting}
{
  "type": "transmitter",
  "action" : "changed",
  "name": "db0abc",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{Transmitter deleted}
\begin{lstlisting}
{
  "type": "transmitter",
  "action" : "deleted",
  "name": "db0abc"
\end{lstlisting}

\subsubsection{User related}
\texttt{New User added}
\begin{lstlisting}
{
  "type": "user",
  "action" : "added",
  "name": "db1abc",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{Existing user changed}
\begin{lstlisting}
{
  "type": "user",
  "action" : "changed",
  "name": "db1abc",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{User deleted}
\begin{lstlisting}
{
  "type": "user",
  "action" : "deleted",
  "name": "db1abc"
}
\end{lstlisting}


\subsubsection{Rubric related}
\texttt{New Rubric added}
\begin{lstlisting}
{
  "type": "rubric",
  "action" : "added",
  "id": "...",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{Existing rubric changed}
\begin{lstlisting}
{
  "type": "user",
  "action" : "changed",
  "id": "...",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{Rubric deleted}
\begin{lstlisting}
{
  "type": "user",
  "action" : "deleted",
  "id": "..."
}
\end{lstlisting}

\subsubsection{Rubric content related}
\todo{Check against CouchDB structure}

\texttt{New Rubric content added}
\begin{lstlisting}
{
  "type": "rubric_content",
  "action" : "added",
  "id": "...??",
  "data" : {
  (Complete Data dump of all ten rubric messages as stored in CouchDB)
  }
}
\end{lstlisting}

\texttt{Existing rubric changed}
\begin{lstlisting}
{
  "type": "rubric_content",
  "action" : "changed",
  "id": "...",
  "data" : {
  (Complete Data dump of all ten rubric messages as stored in CouchDB)
  }
}
\end{lstlisting}

\texttt{Rubric content deleted}
\begin{lstlisting}
{
  "type": "rubric_content",
  "action" : "deleted",
  "id": "..."
  "data" : {
  (Complete Data dump of all ten rubric messages as stored in CouchDB, some may be empty)
  }
}
\end{lstlisting}


\subsubsection{Node related}
\texttt{New node added}
\begin{lstlisting}
{
  "type": "node",
  "action" : "added",
  "name": "db0abc",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{Existing node changed}
\begin{lstlisting}
{
  "type": "node",
  "action" : "changed",
  "name": "db0abc",
  "data" : {
  (Data from CouchDB Change feed in processed way)
  }
}
\end{lstlisting}

\texttt{Node deleted}
\begin{lstlisting}
{
  "type": "node",
  "action" : "deleted",
  "name": "db1abc"
}
\end{lstlisting}

\newpage
\section{CouchDB Documents and Structure}
\todo{als Tabelle darstellen}

\subsection{Users}

\begin{table}[h]
 \centering
 \caption{CouchDB: Users}
 \begin{tabular}{|l|l|l|l|} \hline
  Key & Value-Type & Valid Value Range & Example \\
  \hline
  \_id & string & & dl1abc \\
  password & string & bcrypt hash & --- \\
  email & string & & dl1abc@darc.de \\
  role & string & "admin"|"support"|"user"|"thirdparty.[aprs|brandmeister]" & true \\
  enabled & boolean & & true \\
  created\_on & string & ISO8601 & 2018-07-08T11:50:02.168325Z \\
  created\_by & string & valid user name & dh3wr \\
  changed\_on & string & ISO8601 & 2018-07-08T11:50:02.168325Z \\
  changed\_by & string & valid user name & dh3wr \\
  email\_lastchecked & string & ISO8601 & 2018-07-08T11:50:02.168325Z \\
  avatar\_picture & couchdb\_attachment & & \\ \hline
  \end{tabular}
  \label{tab:couchdb:users}
\end{table}

\begin{lstlisting}
{
  "_id": "dl1abc",
  "password": "<bcrypt hash>",
  "email": "dl1abc@darc.de",
  "roles": ["admin"],
  "enabled": true,
  "created_on": "2018-07-03T08:00:52.786458Z",
  "created_by": "dh3wr",
  "changed_on": "2018-07-03T08:00:52.786458Z",
  "changed_by":"dh3wr",
  "email_lastchecked": "2018-07-03T08:00:52.786458Z",
  "defaults": {
    "subscribers": ["dh3wr",...],
    "subscriber\_groups": [...],
    "transmitters": [...],
    "transmitter\_groups": [...],
    "expiration\_duration": 120,
    "priority" : 1 to 5
  }
  "avatar_picture": <couchdb attachment>
}
\end{lstlisting}


\subsection{Nodes}
\begin{table}[h]
 \caption{CouchDB: Nodes}
 \begin{tabular}{|l|l|l|l|} \hline
  Key & Value-Type & Valid Value Range & Example \\
  \hline
  \_id & STRING & N/A & db0abc \\
  coordinates & [number; 2]  & [lat, lon] & [34.123456, 6.23144] \\
  description & string & whatever & Aachen, Germany\\
  hamcloud & boolean & true/false & true \\
  created\_on & string & ISO8601 & 2018-07-08T11:50:02.168325Z \\
  created\_by & string & valid user name & dh3wr \\
  changed\_on & string & ISO8601 & 2018-07-08T11:50:02.168325Z \\
  changed\_by & string & valid user name & dh3wr \\
  owners & [string] & N/A & ["dl1abc","dh3wr","dl2ic"] \\
  avatar\_picture & couchdb\_attachment & & \\ \hline
  \end{tabular}
  \label{tab:couchdb:nodes}
\end{table}

\begin{lstlisting}
{
  "_id": "db0abc",
  "auth_key": "super_secret_key",
  "coordinates": [34.123456, -23.123456],
  "description": "some words about that node",
  "hamcloud": true,
  "created_on": "2018-07-03T08:00:52.786458Z",
  "created_by":"dh3wr",
  "changed_on": "2018-07-03T08:00:52.786458Z",
  "changed_by":"dh3wr",
  "owners": ["dl1abc","dh3wr","dl2ic"],
  "avatar_picture": <couchdb attachment??>
}
\end{lstlisting}

\subsection{Transmitters}
\todo{Tabelle weiter machen}
\begin{table}[h]
 \caption{CouchDB: Transmitters}
 \begin{tabular}{|l|l|l|l|}\hline
  Key & Value-Type & Valid Value Range & Example \\
  \hline
  \_id & string & N/A & db0abc \\
  auth\_key & string & N/A & asd2FD3q3rF \\
  enabled & boolean & true/false & true \\
  usage & string & PERSONAL | WIDERANGE & WIDERANGE \\
  coordinates & [number; 2]  & [lat, lon] & [34.123456, 6.23144] \\
  power & number & 0.001 ...  & 12.3 \\
  created\_on & string & ISO8601 & 2018-07-08T11:50:02.168325Z \\
  created\_by & string & valid user name & dh3wr \\
  changed\_on & string & ISO8601 & 2018-07-08T11:50:02.168325Z \\
  changed\_by & string & valid user name & dh3wr \\
  owners & ARRAY of STRING & N/A & ["dl1abc","dh3wr","dl2ic"] \\
  avatar\_picture & couchdb\_attachment & & \\ \hline
  \end{tabular}
  \label{tab:couchdb:transmitters}
\end{table}

\begin{lstlisting}
{
  "_id": "db0abc",
  "auth_key": "hdjaskhdlj",
  "enabled": true,
  "usage": "personal" | "widerange",
  "coordinates": [34.123456, -23.123456],
  "power": 12.3,
  "antenna": {
    "agl": 23.4,
    "gain": 2.34,
    "type": "omni" | "directional",
    "direction": 123.2,
    "cable_loss": 4.2
  }
  "owners" : ["dl1abc","dh3wr","dl2ic"],
  "groups" : ["dl-hh", "dl-all"],
  "emergency_power": {
    "available": false,
    "infinite": false,
    "duration": 23*60*60 // seconds
  },
  "created_on": "2018-07-03T08:00:52.786458Z",
  "created_by": "dh3wr",
  "changed_on": "2018-07-03T08:00:52.786458Z",
  "changed_by": "dh3wr",
  "aprs_broadcast": false,
  "transmit_rubrics_format": ["SKYPER","PLAIN"],
  "antenna_pattern" : <couchDB attachment>,
  "avatar_picture" : <couchDB attachment>,
  "simplified_coverage_polygon": [34.1, -23.3, 34.1 -23.2, 34.3, -23.3],
  "coverage_edges": [
  	[lat1, long1],
  	[lat2, long2],
  	[lat3, long3],
  	[lat4, long4]
  ]
}
\end{lstlisting}


\subsection{Subscribers}
\label{protocoldef:couchdb:subscribers}
\todo{check if [] is valid JSON}
\textbf{If type is "Skyper", function is always 3. Keep this in mind }
\begin{lstlisting}
{
  "_id" : "dl1abc",
  "description" : "Peter",
  "pagers" : [
    {
      "ric": 123456,
      "function": 0 .. 3,
      "name": "Peters Alphapoc",
      "type" : "UNKNOWN" | "Skyper" | "AlphaPoc" | "QUIX" | "Swissphone" | "SCALL_XT" | "Birdy"
      "enabled" : true
    },
    ...
  ],
  "third_party_services" : ["APRS", "BM"],
  "owner": ["dh3wr", "dl1abc"],
  "groups" : ["rwth-afu"]
}
\end{lstlisting}


\subsection{Rubrics}
\label{rubrics}

\begin{lstlisting}
{
  "_id": "wx-dl-hh"
  "number": 14,
  "description": "Wetter DL-HH",
  "label": "WX DL-HH",
  "transmitter_groups": ["dl-hh", "dl-ns"],
  "transmitters": ["db0abc"],
  "cyclic_transmit": true,
  "cyclic_transmit_interval": 3600, // seconds
  "owner" : ["dh3wr", "dl1abc"],
  "content": [
  "message1",
  ...,
  "message10"
  ]
}
\end{lstlisting}

\subsection{MQTT services and subscribers}
\label{protocoldef:couchdb:mqttservicesandsubscribers}
\begin{lstlisting}
{
  "_id": "APRS",
  "topic": "aprs"
  "subscribers": [
    {
      "name": "example",
      "password": "<bcrypt hash>"
    },
    ...
  ]
}
\end{lstlisting}