\subsection*{Problem}

A standard way of describing R\+E\+ST A\+P\+Is offered by tools and plugins for Elektra is required to ease development for and usage of these. Because many good standards for describing A\+P\+Is are out there already, an existing one shall be used.

\subsection*{Constraints}


\begin{DoxyItemize}
\item The chosen standard should support Markdown syntax
\item A\+PI 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 A\+PI description
\end{DoxyItemize}

\subsubsection*{Soft-\/\+Constraints}


\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}

\subsection*{Assumptions}


\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 R\+E\+ST A\+P\+Is are simple enough to be allegeable by the chosen standard, also in future.
\end{DoxyItemize}

\subsection*{Considered Alternatives}


\begin{DoxyItemize}
\item \href{http://swagger.io/}{\tt Swagger}
\item \href{https://apiary.io/}{\tt apiary} with \href{https://apiblueprint.org/}{\tt A\+PI blueprints}
\item \href{http://raml.org/}{\tt R\+A\+ML}
\end{DoxyItemize}

\subsection*{Decision}

The decision is to use \href{https://apiblueprint.org/}{\tt A\+PI blueprints} together with additional tools from its ecosystem.

\subsection*{Rationale}

{\bfseries A\+PI 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 A\+PI, {\bfseries A\+PI Blueprints} also supports schemata modeling, which is more precise than giving examples for requests and responses.

\subsection*{Implication}


\begin{DoxyItemize}
\item A\+PI descriptions should also follow other conventions like the usage of similar error codes.
\end{DoxyItemize}

\subsection*{Notes}

There are many tools available to use with {\bfseries A\+PI Blueprints}, for example the \href{https://github.com/apiaryio/apiary-client}{\tt C\+LI tool} of apiary. Other tools can be found on the \href{https://apiblueprint.org/tools.html}{\tt official website} of the standard.

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