Begin chapter 1

Author: pathawks

chapters/01Introduction.tex

@@ -0,0 +1,86 @@
+\chapter{Introduction}
+\section{Using the URLs}
+
+Except for noted exceptions, URLs documented in the functions below are suffixes of the following URL, which points to the secure resources of Starexec.
+\\\url{https://www.starexec.org/starexec/secure/}\\
+
+The largest exception to this is that all URLs that begin with ?services? do not have the ?secure? prefix. So, any URL that begins with services/ is a suffix of the following URL.
+\\\url{https://www.starexec.org/starexec/}\\
+
+Other exceptions are noted where applicable in the function documentation.
+
+
+\section{Logging In}
+
+To be able to access Starexec resources, you will need to log into Starexec and maintain a secure channel. Logging in is a multistep protocol, with 3 main steps. First, authorization works on a challenge-based system, which means you cannot log in until you request a secure resource. Next, you must provide your username and password, and finally, you will access a secure resource.
+
+\subsection{First Step -- Requesting a Secure Resource}
+
+\begin{description}
+\item [URL] index.jsp
+\item [Method] GET
+\item [Parameter Encoding] N/A
+\item [Returns] The login page
+\item [Return Cookies] \
+
+	\begin{description}
+	\item [JSESSIONID] \type{Integer} On success, contains a session ID that you will need to use in later steps.
+	\end{description}
+\end{description}
+
+\subsection{Second Step -- Providing Login Credentials}
+
+\begin{description}
+\item [URL] j\_security\_check
+\item [Method] POST
+\item [Parameter Encoding] application/x-www-form-urlencoded
+\item [Parameters] \
+    \begin{description}
+    \item [j\_username] \type{String} Your username
+    \item [j\_password] \type{String} Your password
+    \item [cookieexists] \type{Boolean} Should be set to false for web API calls
+    \end{description}
+
+\item [Description] Logs you into Starexec. You must provide the JSESSIONID you acquired in the previous steps.
+\item [Returns] A jSON string containing a status object
+\end{description}
+
+\subsection{Third Step -- Accessing Secure Resources}
+
+\begin{description}
+\item [URL] index.jsp
+\item [Method] GET
+\item [Parameter Encoding] N/A
+\item [Returns] The login page
+\item [Return Cookies] \
+	\begin{description}
+	\item [JSESSIONID] \type{Integer} On success, contains a new session ID. You must begin using this new session ID for all subsequent interactions.
+	\end{description}
+\end{description}
+
+\section{Maintaining a Session}
+After you have logged in, you must maintain a session for as long as you want to make requests to the secure resources of Starexec. To maintain a session, your HTTP requests should have the following header keys with the appropriate values.
+
+\begin{description}
+\item [Cookie] \type{String} Should contain a string of the form ``killmenothing; JSESSIONID=" + your JSESSIONID obtained when logging in.
+\item [Connection] \type{String} Should be ``keep-alive"
+\item [Accept-Language] \type{String} Should be ``en-US,en;q=0.5"
+\end{description}
+
+\section{Permissions}
+
+Several functions below accept all of the following permissions parameters.
+
+\begin{description}
+\item [addBench] \type{Boolean} Whether default permissions for this space should include adding benchmarks
+\item [addJob] \type{Boolean} Whether default permissions for this space should include adding jobs
+\item [addSolver] \type{Boolean} Whether default permissions for this space should include adding solvers
+\item [addSpace] \type{Boolean} Whether default permissions for this space should include adding spaces
+\item [addUser] \type{Boolean} Whether default permissions for this space should include adding users
+\item [removeBench] \type{Boolean} Whether default permissions for this space should include removing benchmarks
+\item [removeJob] \type{Boolean} Whether default permissions for this space should include removing jobs
+\item [removeSolver] \type{Boolean} Whether default permissions for this space should include removing solvers
+\item [removeSpace] \type{Boolean} Whether default permissions for this space should include removing spaces
+\item [removeUser] \type{Boolean} Whether default permissions for this space should include removing users
+\item [isLeader] \type{Boolean} Whether the a user should be a leader or not.
+\end{description}