ProvSAP is a simple data access layer interface \citep[see DALI specification of the VO, ][]{std:DALI} that can be implemented by a web service to serve provenance information to a client.
%It follows the basic DALI principles of the VO as detailed in \citep[see][]{std:DALI}.
The client sends a GET request to the basic URL endpoint (\texttt{\{provsap-base-url\}}) of a ProvSAP service, providing at least the main parameter {\bf ID}, the (unique, qualified) identifier of an entity (obs\_publisher\_did of an ObsDataSet for example), activity or an agent. This parameter can occur more than once in a request in order to retrieve provenance details for several activities, datasets or agents at the same time. Here are two simple example requests:

\begin{verbatim}
{provsap-base-url}?ID=rave:dr4
{provsap-base-url}?ID=rave:dr4&ID=rave:act_irafReduction
\end{verbatim}
\noindent
Additional parameters can complete the request to refine the query. They are described in the next paragraphs and summarized in Table~\ref{tab:provsap-parameters}.

\begin{table}[h]
\small
\begin{tabulary}{1.0\textwidth}{@{}p{0.25\textwidth}p{0.23\textwidth}p{0.45\textwidth}@{}}
%{llp{0.2\textwidth}p{0.3\textwidth}}
\toprule
\head{Parameter} & \head{Values} & \head{Description}\\
\midrule
\textbf{\urlparam{ID}} & qualified \urlparam{ID} & a valid qualified identifier for an entity, activity or agent (can occur multiple times)\\
\textbf{\urlparam{DEPTH}} & 0,\underline{1},2,..., \urlparam{ALL} &  number of relations to be followed or \texttt{ALL} for everything, independent of the relation type\\
\textbf{\urlparam{RESPONSEFORMAT}} & \urlparam{PROV-N}, \newline\urlparam{\underline{PROV-JSON}}, \newline\urlparam{PROV-XML}, \newline\urlparam{PROV-VOTABLE} & serialisation format of the response\\\hline
\urlparam{DIRECTION} & \urlparam{\underline{BACK}}, \urlparam{FORTH} & \urlparam{BACK} = track the provenance history, \newline\urlparam{FORTH} = explore the results of activities and where entities have been used\\
\urlparam{MEMBERS} & \urlparam{true} (1) or \urlparam{\underline{false}} (0) & if \urlparam{true}/1, retrieve and track members of collections\\
\urlparam{STEPS} & \urlparam{true} (1) or \urlparam{\underline{false}} (0) & if \urlparam{true}/1, retrieve and track steps of activityFlows\\
\urlparam{AGENT} & \urlparam{true} (1) or \urlparam{\underline{false}} (0) & if \urlparam{true}/1, explore all relations for agents, i.e. find out what an agent is responsible for\\
\urlparam{MODEL} & \urlparam{\underline{IVOA}} or \urlparam{W3C} & compatibility of the serialization to the IVOA or W3C provenance data model\\
\bottomrule
\end{tabulary}
\caption[ProvSAP request parameters]{ProvSAP request parameters. Options that are \textbf{required} to be implemented by ProvSAP services are marked with bold face. \underline{Default} values are underlined. The parameter names are case-insensitive, but the parameter values are not.}
\label{tab:provsap-parameters}
\end{table}


\paragraph{RESPONSEFORMAT}
The format of the response can be defined using the RESPONSEFORMAT parameter. Its value is one of the provenance serialization formats: PROV-N, PROV-JSON, PROV-XML, PROV-VOTABLE.

\paragraph{{DEPTH}}
The DEPTH parameter gives the number of relations that shall be tracked along
the provenance history -- independent of the type of relation. Its value is
either 0, a positive integer or ALL. If this parameter is omitted,
the default is 1, which returns all relations and nodes that can be reached
by following 1 relation. If \texttt{DEPTH=ALL} is requested, the server should
return the complete provenance history that the service has stored for the
given entity, activity or agent.
Services may restrict the returned data by
redirecting \texttt{DEPTH=ALL} to \texttt{DEPTH=\{maxdepth\}}, where
\texttt{\{maxdepth\}} is an integer defining the maximum depth number that
the server allows.

If description classes (EntityDescription etc.) are used, we expect that the descriptions are retrieved together with each corresponding main class. For example, for each entity node also return the entityDescription -- either by adding the description attributes to the entity in the serialized response, by adding a link to a URL with entityDescription information or by returning a
direct serialization of the description class along with a link from the entity to the entityDescription.


Note that the relations \emph{wasDerivedFrom} and \emph{wasInformedBy} are ``short-cuts''
in a provenance graph. Thus for e.g. \texttt{DEPTH=2} more progenitors of an entity may
be reached via \emph{wasDerivedFrom} relations than via the ``long path'' along the
corresponding \emph{used} and \emph{wasGeneratedBy} relations (see e.g. progenitor entity E1 in
Figure~\ref{fig:provenance-graph-example}).
%Whenever DEPTH is not ALL, the client has to accept that
%the returned part of a provenance graph may not be complete and that nodes may be returned
%which are related to each other but the relations are not shown (yet).
%(because they would only appear if DEPTH is increased.)
(A better solution for the future may be to use 1/2*DEPTH for walking along these short-cut relations, but we don't want to make ProvSAP more complex for now.)

% \noindent
% The format can also be specified via the HTTP accept header, e.g.
% \begin{verbatim}
% wget -d --header="Accept: application/json" \
%    {provsap-base-url}?ID=rave:dr4
% \end{verbatim}
% would return the provenance information in \urlparam{PROV-JSON} format.
% \noindent
% If both \urlparam{FORMAT} and the accept header are used and \urlparam{FORMAT} specifies a format that is incompatible with the HTTP accept header, then the service should return with a HTTP status 406: Not Acceptable.

\paragraph{DIRECTION}
For services which allow tracking the provenance information forward, e.g. in order to check for which activities an entity was used, the optional parameter DIRECTION can be set to FORTH. Its default value is BACK. This only influences the direction in which the used, wasGeneratedBy, wasDerivedFrom and wasInfluencedBy relations are followed. Any other relations are tracked according to the behaviour specified below, independent of the DIRECTION value.


Figure~\ref{fig:provenance-graph-example} shows an example provenance graph with different relations and nodes. Only the relations marked by solid lines are influenced by the DIRECTION parameter. A ProvSAP GET request with \texttt{ID=E6} and \texttt{DEPTH=2} returns only the highlighted nodes and relations (thick lines) by default.

\begin{figure}[h]
\centering
\includegraphics[width=1.0\textwidth]{provenance-graph-example-depth2.pdf}
\caption[Example provenance graph for ProvSAP]{An example provenance graph, highlighting the objects and relations returned from a ProvSAP service with \texttt{ID=E6} and \texttt{DEPTH=2}. The BACK and FORTH values for DIRECTION are only important for the processing relations (solid lines). Hierarchial (dashed) and responsibility (dotted) relations are only followed ``upwards'' (to collection/activityFlow) and towards agents by default (unless the optional parameters MEMBERS, STEPS and/or AGENT are set to true.}
\label{fig:provenance-graph-example}
\end{figure}




\paragraph{MEMBERS, STEPS}
The provenance data model defines the hierarchical relations \emph{hadMember} for entity collections and \emph{hadStep} for activityFlows. If a node belongs to a collection or activityFlow, these relations shall be returned as well, independent of the specified tracking direction.
If someone is interested in more details and wants to follow the \emph{members} of an entity collection or the \emph{steps} of an activityFlow, these can be included by setting the optional parameter MEMBERS or STEPS to true, respectively. The default is false. As detailed in DALI \citep{std:DALI}, the values 1 and 0 are equivalent to true and false.

\paragraph{AGENT}
By default, it is recommended to stop any further tracking at an agent node, unless an additional optional parameter AGENT is set to true. Note that this means that the request for any agent will always return just the agent node itself and nothing else, unless AGENT=true is used. An example request if one wants to know which entities and activities an agent has influenced could look like this:\\
\texttt{\{provsap-base-url\}?ID=org:rave\&AGENT=true\&DEPTH=1}.\\
\texttt{DEPTH=1} is used here in order to avoid following the found entities and activities any further (can be omitted, since this is the default for DEPTH).
%\comment{Maybe it's better to use DEPTH and DIRECTION instead of FORWARD and BACKWARD. Reason: if a service just implements the backward direction, then it's weird to call something ``backward'' if there is no ``forward'' as well. DEPTH is also a commonly used word when refering to graphs and numbers of relations.}


\paragraph{MODEL}
If a provenance service supports it, the MODEL parameter is used to distinguish between serializations compatible with the IVOA or the W3C provenance data model. The default value is IVOA.
\newline



A ProvSAP service MUST implement the parameters ID, DEPTH and RESPONSEFORMAT; the remaining parameters are optional.
If a service does not implement the optional parameters, but they appear in the request, then the service should return with an error.
Please note that according to the DALI specification \citep{std:DALI}, the parameter names are case-insensitive, but the parameter values are not. E.g. \texttt{direction=FORTH} is allowed, but \texttt{DIRECTION=forth} may not work.




\section{Example use cases -- maybe expand here, or skip}
Here are a few example use cases for ProvSAP in order to show its usefulness for astronomical datasets.

\begin{itemize}
\item The RAVE DR4 release contains a main table with stellar properties for each observation of a star. Given the RAVE observation ID, retrieve all the processing steps
for this specific observation result:

	\begin{verbatim}
	{provsap-base-url}?ID=rave:20121220_0752m38_089&DEPTH=ALL
	\end{verbatim}

The result will not only contain the processing steps (activities), but also entities and agents. The information that the user is actually interested in can be filtered out by a client application (e.g. using the  voprov python package). If a W3C tool shall be used, e.g. when the result shall be loaded to ProvStore\footnote{https://provenance.ecs.soton.ac.uk/store/} for further processing, one needs to retrieve the information in a W3C compatible way like this:

	\begin{verbatim}
	{provsap-base-url}?ID=rave:20121220_0752m38_089&DEPTH=ALL&MODEL=W3C
	\end{verbatim}

\item Get the direct progenitor of an entity:
	\begin{verbatim}
	{provsap-base-url}?ID=rave:20121220_0752m38_089&DEPTH=1
	\end{verbatim}
	If this request only returns a collection and no ``backwards'' information about progenitors, then one needs to track the collection further, i.e. repeat the request for the collection entity.

\item Get all datasets that were derived from a specific data file in the CTA pipeline:
	\begin{verbatim}
	{provsap-base-url}?ID=cta:df1&DEPTH=ALL&DIRECTION=FORTH
	\end{verbatim}
%	By using \texttt{DIRECTION=FORTH} we can track the dataset and where it was used forward.

\end{itemize}

ProvSAP is meant to be used to just retrieve parts of a provenance graph from a provenance web service. It cannot be used to explore the provenance graphs and filter the information based on specific properties, e.g. the creationTime of an entity or a parameter value for an activity. For such cases, a ProvTAP service can be used -- which is described in the next section.


