\label{doc_decisions_rest_api_documentation_md_md_doc_decisions_rest_api_documentation}%
\Hypertarget{doc_decisions_rest_api_documentation_md_md_doc_decisions_rest_api_documentation}%
 \hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2123}{}\doxysection{Problem}\label{doc_decisions_rest_api_documentation_md_autotoc_md2123}
A standard way of describing REST APIs offered by tools and plugins for Elektra is required to ease development for and usage of these. Because many good standards for describing APIs are out there already, an existing one shall be used.\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2124}{}\doxysection{Constraints}\label{doc_decisions_rest_api_documentation_md_autotoc_md2124}

\begin{DoxyItemize}
\item The chosen standard should support Markdown syntax
\item API descriptions created within the standard should be human-\/readable
\item Only free software should be used
\item To enhance reusability, there should be a separation of data modeling and API description
\end{DoxyItemize}\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2125}{}\doxysubsection{Soft-\/\+Constraints}\label{doc_decisions_rest_api_documentation_md_autotoc_md2125}

\begin{DoxyItemize}
\item (Nice looking) documentation should be generateable from the plain documentation
\item Created documentation should be testable by tools (automatic tests)
\end{DoxyItemize}\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2126}{}\doxysection{Assumptions}\label{doc_decisions_rest_api_documentation_md_autotoc_md2126}

\begin{DoxyItemize}
\item There is a well-\/suited standard with enough (free) tools available to satisfy all or most constraints.
\item Scenarios created by Elektra REST APIs are simple enough to be allegeable by the chosen standard, also in the future.
\end{DoxyItemize}\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2127}{}\doxysection{Considered Alternatives}\label{doc_decisions_rest_api_documentation_md_autotoc_md2127}

\begin{DoxyItemize}
\item \href{http://swagger.io/}{\texttt{ Swagger}}
\item \href{https://apiary.io/}{\texttt{ apiary}} with \href{https://apiblueprint.org/}{\texttt{ API blueprints}}
\item \href{http://raml.org/}{\texttt{ RAML}}
\end{DoxyItemize}\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2128}{}\doxysection{Decision}\label{doc_decisions_rest_api_documentation_md_autotoc_md2128}
The decision is to use \href{https://apiblueprint.org/}{\texttt{ API blueprints}} together with additional tools from its ecosystem.\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2129}{}\doxysection{Rationale}\label{doc_decisions_rest_api_documentation_md_autotoc_md2129}
{\bfseries{API Blueprints}} together with some (free) tools for it support all given constraints and also all soft-\/constraints. It also fits the current documentation style of the Elektra Initiative the most.

Additionally to modeling data apart from the API, {\bfseries{API Blueprints}} also supports schemata modeling, which is more precise than giving examples for requests and responses.\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2130}{}\doxysection{Implication}\label{doc_decisions_rest_api_documentation_md_autotoc_md2130}

\begin{DoxyItemize}
\item API descriptions should also follow other conventions like the usage of similar error codes.
\end{DoxyItemize}\hypertarget{doc_decisions_rest_api_documentation_md_autotoc_md2131}{}\doxysection{Notes}\label{doc_decisions_rest_api_documentation_md_autotoc_md2131}
There are many tools available to use with {\bfseries{API Blueprints}}, for example the \href{https://github.com/apiaryio/apiary-client}{\texttt{ CLI tool}} of apiary. Other tools can be found on the \href{https://apiblueprint.org/tools.html}{\texttt{ official website}} of the standard.

Decision discussions have taken place in \#917. An API proposal for cluster configurations was made in \#912, whereas initial discussion started in \#829. 