update auth endpoints documentation - #21

docs/_sources/api/auth.rst.txt

@@ -1,8 +1,6 @@
 Authentication
 ##############
 
-work in progress
-
 .. autoflask:: fittrackee_api:create_app()
    :endpoints:
     auth.register_user,

docs/api/activities.html

@@ -461,7 +461,7 @@
 </dd>
 <dt class="field-even">Form Parameters</dt>
 <dd class="field-even"><ul class="simple">
-<li><p><strong>file</strong> – gpx file</p></li>
+<li><p><strong>file</strong> – gpx file (allowed extensions: .gpx, .zip)</p></li>
 <li><p><strong>data</strong> – sport id and notes (example: <code class="docutils literal notranslate"><span class="pre">{&quot;sport_id&quot;:</span> <span class="pre">1,</span> <span class="pre">&quot;notes&quot;:</span> <span class="pre">&quot;&quot;}</span></code>)</p></li>
 </ul>
 </dd>
@@ -473,7 +473,13 @@
 <dt class="field-even">Status Codes</dt>
 <dd class="field-even"><ul class="simple">
 <li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2">201 Created</a> – activity created</p></li>
-<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1">400 Bad Request</a> – invalid payload</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1">400 Bad Request</a> – <ul>
+<li><p>Invalid payload.</p></li>
+<li><p>No file part.</p></li>
+<li><p>No selected file.</p></li>
+<li><p>File extension not allowed.</p></li>
+</ul>
+</p></li>
 <li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">401 Unauthorized</a> – invalid token</p></li>
 <li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – </p></li>
 </ul>
@@ -757,7 +763,7 @@
 <li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5">204 No Content</a> – activity deleted</p></li>
 <li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">401 Unauthorized</a> – invalid token</p></li>
 <li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5">404 Not Found</a> – activity not found</p></li>
-<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – </p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – Error. Please try again or contact the administrator.</p></li>
 </ul>
 </dd>
 </dl>

docs/api/auth.html

@@ -123,47 +123,387 @@
       
   <div class="section" id="authentication">
 <h1>Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h1>
-<p>work in progress</p>
 <dl class="post">
 <dt id="post--api-auth-register">
 <code class="sig-name descname">POST </code><code class="sig-name descname">/api/auth/register</code><a class="headerlink" href="#post--api-auth-register" title="Permalink to this definition">¶</a></dt>
 <dd><p>register a user</p>
+<p><strong>Example request</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">POST</span> <span class="nn">/auth/register</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+</pre></div>
+</div>
+<p><strong>Example responses</strong>:</p>
+<ul class="simple">
+<li><p>successful registration</p></li>
+</ul>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">201</span> <span class="ne">CREATED</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;auth_token&quot;</span><span class="p">:</span> <span class="s2">&quot;JSON Web Token&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Successfully registered.&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><p>error on registration</p></li>
+</ul>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">400</span> <span class="ne">BAD REQUEST</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Errors: Valid email must be provided.\n&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;error&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<dl class="field-list simple">
+<dt class="field-odd">Request JSON Object</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>username</strong> (<em>string</em>) – user name (3 to 12 characters required)</p></li>
+<li><p><strong>email</strong> (<em>string</em>) – user email</p></li>
+<li><p><strong>password</strong> (<em>string</em>) – password (8 characters required)</p></li>
+<li><p><strong>password_conf</strong> (<em>string</em>) – password confirmation</p></li>
+</ul>
+</dd>
+<dt class="field-even">Status Codes</dt>
+<dd class="field-even"><ul class="simple">
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2">201 Created</a> – Successfully registered.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1">400 Bad Request</a> – <ul>
+<li><p>Invalid payload.</p></li>
+<li><p>Sorry. That user already exists.</p></li>
+<li><dl class="simple">
+<dt>Errors:</dt><dd><ul>
+<li><p>Username: 3 to 12 characters required.</p></li>
+<li><p>Valid email must be provided.</p></li>
+<li><p>Password and password confirmation don’t match.</p></li>
+<li><p>Password: 8 characters required.</p></li>
+</ul>
+</dd>
+</dl>
+</li>
+</ul>
+</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – Error. Please try again or contact the administrator.</p></li>
+</ul>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="post">
 <dt id="post--api-auth-login">
 <code class="sig-name descname">POST </code><code class="sig-name descname">/api/auth/login</code><a class="headerlink" href="#post--api-auth-login" title="Permalink to this definition">¶</a></dt>
 <dd><p>user login</p>
+<p><strong>Example request</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">POST</span> <span class="nn">/auth/login</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+</pre></div>
+</div>
+<p><strong>Example responses</strong>:</p>
+<ul class="simple">
+<li><p>successful login</p></li>
+</ul>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;auth_token&quot;</span><span class="p">:</span> <span class="s2">&quot;JSON Web Token&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Successfully logged in.&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><p>error on login</p></li>
+</ul>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">404</span> <span class="ne">NOT FOUND</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Invalid credentials.&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;error&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<dl class="field-list simple">
+<dt class="field-odd">Request JSON Object</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>email</strong> (<em>string</em>) – user email</p></li>
+<li><p><strong>password_conf</strong> (<em>string</em>) – password confirmation</p></li>
+</ul>
+</dd>
+<dt class="field-even">Status Codes</dt>
+<dd class="field-even"><ul class="simple">
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1">200 OK</a> – Successfully logged in.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5">404 Not Found</a> – Invalid credentials.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – Error. Please try again or contact the administrator.</p></li>
+</ul>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="get">
 <dt id="get--api-auth-logout">
 <code class="sig-name descname">GET </code><code class="sig-name descname">/api/auth/logout</code><a class="headerlink" href="#get--api-auth-logout" title="Permalink to this definition">¶</a></dt>
 <dd><p>user logout</p>
+<p><strong>Example request</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/auth/logout</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+</pre></div>
+</div>
+<p><strong>Example responses</strong>:</p>
+<ul class="simple">
+<li><p>successful logout</p></li>
+</ul>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Successfully logged out.&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><p>error on login</p></li>
+</ul>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">401</span> <span class="ne">UNAUTHORIZED</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Provide a valid auth token.&quot;</span><span class="p">,</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;error&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<dl class="field-list simple">
+<dt class="field-odd">Request Headers</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><a class="reference external" href="https://tools.ietf.org/html/rfc7235#section-4.2">Authorization</a> – OAuth 2.0 Bearer Token</p></li>
+</ul>
+</dd>
+<dt class="field-even">Status Codes</dt>
+<dd class="field-even"><ul class="simple">
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1">200 OK</a> – Successfully logged out.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">401 Unauthorized</a> – Provide a valid auth token.</p></li>
+</ul>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="get">
 <dt id="get--api-auth-profile">
 <code class="sig-name descname">GET </code><code class="sig-name descname">/api/auth/profile</code><a class="headerlink" href="#get--api-auth-profile" title="Permalink to this definition">¶</a></dt>
 <dd><p>get authenticated user info</p>
+<p><strong>Example request</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/auth/profile</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+</pre></div>
+</div>
+<p><strong>Example response</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;data&quot;</span><span class="p">:</span> <span class="p">{</span>
+    <span class="nt">&quot;admin&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
+    <span class="nt">&quot;bio&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;birth_date&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;created_at&quot;</span><span class="p">:</span> <span class="s2">&quot;Sun, 14 Jul 2019 14:09:58 GMT&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;admin@example.com&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;first_name&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;id&quot;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
+    <span class="nt">&quot;last_name&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;location&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;nb_activities&quot;</span><span class="p">:</span> <span class="mi">6</span><span class="p">,</span>
+    <span class="nt">&quot;nb_sports&quot;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span>
+    <span class="nt">&quot;picture&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
+    <span class="nt">&quot;timezone&quot;</span><span class="p">:</span> <span class="s2">&quot;Europe/Paris&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;total_distance&quot;</span><span class="p">:</span> <span class="mf">67.895</span><span class="p">,</span>
+    <span class="nt">&quot;total_duration&quot;</span><span class="p">:</span> <span class="s2">&quot;6:50:27&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;username&quot;</span><span class="p">:</span> <span class="s2">&quot;sam&quot;</span>
+  <span class="p">},</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<dl class="field-list simple">
+<dt class="field-odd">Request Headers</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><a class="reference external" href="https://tools.ietf.org/html/rfc7235#section-4.2">Authorization</a> – OAuth 2.0 Bearer Token</p></li>
+</ul>
+</dd>
+<dt class="field-even">Status Codes</dt>
+<dd class="field-even"><ul class="simple">
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1">200 OK</a> – success.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">401 Unauthorized</a> – Provide a valid auth token.</p></li>
+</ul>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="post">
 <dt id="post--api-auth-profile-edit">
 <code class="sig-name descname">POST </code><code class="sig-name descname">/api/auth/profile/edit</code><a class="headerlink" href="#post--api-auth-profile-edit" title="Permalink to this definition">¶</a></dt>
 <dd><p>edit authenticated user</p>
+<p><strong>Example request</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">POST</span> <span class="nn">/auth/profile/edit</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+</pre></div>
+</div>
+<p><strong>Example response</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;data&quot;</span><span class="p">:</span> <span class="p">{</span>
+    <span class="nt">&quot;admin&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
+    <span class="nt">&quot;bio&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;birth_date&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;created_at&quot;</span><span class="p">:</span> <span class="s2">&quot;Sun, 14 Jul 2019 14:09:58 GMT&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;admin@example.com&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;first_name&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;id&quot;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
+    <span class="nt">&quot;last_name&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;location&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;nb_activities&quot;</span><span class="p">:</span> <span class="mi">6</span><span class="p">,</span>
+    <span class="nt">&quot;nb_sports&quot;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span>
+    <span class="nt">&quot;picture&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
+    <span class="nt">&quot;timezone&quot;</span><span class="p">:</span> <span class="s2">&quot;Europe/Paris&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;total_distance&quot;</span><span class="p">:</span> <span class="mf">67.895</span><span class="p">,</span>
+    <span class="nt">&quot;total_duration&quot;</span><span class="p">:</span> <span class="s2">&quot;6:50:27&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;username&quot;</span><span class="p">:</span> <span class="s2">&quot;sam&quot;</span>
+  <span class="p">},</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<dl class="field-list simple">
+<dt class="field-odd">Request JSON Object</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>first_name</strong> (<em>string</em>) – user first name</p></li>
+<li><p><strong>last_name</strong> (<em>string</em>) – user last name</p></li>
+<li><p><strong>location</strong> (<em>string</em>) – user location</p></li>
+<li><p><strong>bio</strong> (<em>string</em>) – user biography</p></li>
+<li><p><strong>birth_date</strong> (<em>string</em>) – user birth date (format: <code class="docutils literal notranslate"><span class="pre">%Y-%m-%d</span></code>)</p></li>
+<li><p><strong>password</strong> (<em>string</em>) – user password</p></li>
+<li><p><strong>password_conf</strong> (<em>string</em>) – user password confirmation</p></li>
+<li><p><strong>timezone</strong> (<em>string</em>) – user time zone</p></li>
+</ul>
+</dd>
+<dt class="field-even">Request Headers</dt>
+<dd class="field-even"><ul class="simple">
+<li><p><a class="reference external" href="https://tools.ietf.org/html/rfc7235#section-4.2">Authorization</a> – OAuth 2.0 Bearer Token</p></li>
+</ul>
+</dd>
+<dt class="field-odd">Status Codes</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1">200 OK</a> – User profile updated.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1">400 Bad Request</a> – <ul>
+<li><p>Invalid payload.</p></li>
+<li><p>Password and password confirmation don’t match.</p></li>
+</ul>
+</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">401 Unauthorized</a> – Provide a valid auth token.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – Error. Please try again or contact the administrator.</p></li>
+</ul>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="post">
 <dt id="post--api-auth-picture">
 <code class="sig-name descname">POST </code><code class="sig-name descname">/api/auth/picture</code><a class="headerlink" href="#post--api-auth-picture" title="Permalink to this definition">¶</a></dt>
 <dd><p>update authenticated user picture</p>
+<p><strong>Example request</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">POST</span> <span class="nn">/auth/picture</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">multipart/form-data</span>
+</pre></div>
+</div>
+<p><strong>Example response</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+
+<span class="p">{</span>
+  <span class="nt">&quot;data&quot;</span><span class="p">:</span> <span class="p">{</span>
+    <span class="nt">&quot;admin&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
+    <span class="nt">&quot;bio&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;birth_date&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;created_at&quot;</span><span class="p">:</span> <span class="s2">&quot;Sun, 14 Jul 2019 14:09:58 GMT&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;admin@example.com&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;first_name&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;id&quot;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
+    <span class="nt">&quot;last_name&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;location&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
+    <span class="nt">&quot;nb_activities&quot;</span><span class="p">:</span> <span class="mi">6</span><span class="p">,</span>
+    <span class="nt">&quot;nb_sports&quot;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span>
+    <span class="nt">&quot;picture&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
+    <span class="nt">&quot;timezone&quot;</span><span class="p">:</span> <span class="s2">&quot;Europe/Paris&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;total_distance&quot;</span><span class="p">:</span> <span class="mf">67.895</span><span class="p">,</span>
+    <span class="nt">&quot;total_duration&quot;</span><span class="p">:</span> <span class="s2">&quot;6:50:27&quot;</span><span class="p">,</span>
+    <span class="nt">&quot;username&quot;</span><span class="p">:</span> <span class="s2">&quot;sam&quot;</span>
+  <span class="p">},</span>
+  <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<dl class="field-list simple">
+<dt class="field-odd">Form Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>file</strong> – image file (allowed extensions: .jpg, .png, .gif)</p></li>
+</ul>
+</dd>
+<dt class="field-even">Request Headers</dt>
+<dd class="field-even"><ul class="simple">
+<li><p><a class="reference external" href="https://tools.ietf.org/html/rfc7235#section-4.2">Authorization</a> – OAuth 2.0 Bearer Token</p></li>
+</ul>
+</dd>
+<dt class="field-odd">Status Codes</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1">200 OK</a> – User picture updated.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1">400 Bad Request</a> – <ul>
+<li><p>Invalid payload.</p></li>
+<li><p>No file part.</p></li>
+<li><p>No selected file.</p></li>
+<li><p>File extension not allowed.</p></li>
+</ul>
+</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">401 Unauthorized</a> – Provide a valid auth token.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – Error during picture update.</p></li>
+</ul>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="delete">
 <dt id="delete--api-auth-picture">
 <code class="sig-name descname">DELETE </code><code class="sig-name descname">/api/auth/picture</code><a class="headerlink" href="#delete--api-auth-picture" title="Permalink to this definition">¶</a></dt>
 <dd><p>delete authenticated user picture</p>
+<p><strong>Example request</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">DELETE</span> <span class="nn">/auth/picture</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+</pre></div>
+</div>
+<p><strong>Example response</strong>:</p>
+<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">204</span> <span class="ne">NO CONTENT</span>
+<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
+</pre></div>
+</div>
+<dl class="field-list simple">
+<dt class="field-odd">Request Headers</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><a class="reference external" href="https://tools.ietf.org/html/rfc7235#section-4.2">Authorization</a> – OAuth 2.0 Bearer Token</p></li>
+</ul>
+</dd>
+<dt class="field-even">Status Codes</dt>
+<dd class="field-even"><ul class="simple">
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5">204 No Content</a> – picture deleted</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">401 Unauthorized</a> – Provide a valid auth token.</p></li>
+<li><p><a class="reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1">500 Internal Server Error</a> – Error during picture deletion.</p></li>
+</ul>
+</dd>
+</dl>
 </dd></dl>
 
 </div>

docsrc/source/api/auth.rst

@@ -1,8 +1,6 @@
 Authentication
 ##############
 
-work in progress
-
 .. autoflask:: fittrackee_api:create_app()
    :endpoints:
     auth.register_user,

fittrackee_api/fittrackee_api/activities/activities.py

@@ -638,13 +638,17 @@ def post_activity(auth_user_id):
 
     :param integer auth_user_id: authenticate user id
 
-    :form file: gpx file
+    :form file: gpx file (allowed extensions: .gpx, .zip)
     :form data: sport id and notes (example: ``{"sport_id": 1, "notes": ""}``)
 
     :reqheader Authorization: OAuth 2.0 Bearer Token
 
     :statuscode 201: activity created
-    :statuscode 400: invalid payload
+    :statuscode 400:
+        - Invalid payload.
+        - No file part.
+        - No selected file.
+        - File extension not allowed.
     :statuscode 401: invalid token
     :statuscode 500:
 
@@ -1043,7 +1047,7 @@ def delete_activity(auth_user_id, activity_id):
     :statuscode 204: activity deleted
     :statuscode 401: invalid token
     :statuscode 404: activity not found
-    :statuscode 500:
+    :statuscode 500: Error. Please try again or contact the administrator.
 
     """
 

fittrackee_api/fittrackee_api/users/auth.py

@@ -15,7 +15,61 @@ auth_blueprint = Blueprint('auth', __name__)
 
 @auth_blueprint.route('/auth/register', methods=['POST'])
 def register_user():
-    """ register a user """
+    """
+    register a user
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+      POST /auth/register HTTP/1.1
+      Content-Type: application/json
+
+    **Example responses**:
+
+    - successful registration
+
+    .. sourcecode:: http
+
+      HTTP/1.1 201 CREATED
+      Content-Type: application/json
+
+      {
+        "auth_token": "JSON Web Token",
+        "message": "Successfully registered.",
+        "status": "success"
+      }
+
+    - error on registration
+
+    .. sourcecode:: http
+
+      HTTP/1.1 400 BAD REQUEST
+      Content-Type: application/json
+
+      {
+        "message": "Errors: Valid email must be provided.\\n",
+        "status": "error"
+      }
+
+    :<json string username: user name (3 to 12 characters required)
+    :<json string email: user email
+    :<json string password: password (8 characters required)
+    :<json string password_conf: password confirmation
+
+    :statuscode 201: Successfully registered.
+    :statuscode 400:
+        - Invalid payload.
+        - Sorry. That user already exists.
+        - Errors:
+            - Username: 3 to 12 characters required.
+            - Valid email must be provided.
+            - Password and password confirmation don't match.
+            - Password: 8 characters required.
+    :statuscode 500:
+        Error. Please try again or contact the administrator.
+
+    """
     # get post data
     post_data = request.get_json()
     if not post_data or post_data.get('username') is None \
@@ -92,7 +146,51 @@ def register_user():
 
 @auth_blueprint.route('/auth/login', methods=['POST'])
 def login_user():
-    """ user login """
+    """
+    user login
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+      POST /auth/login HTTP/1.1
+      Content-Type: application/json
+
+    **Example responses**:
+
+    - successful login
+
+    .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "auth_token": "JSON Web Token",
+        "message": "Successfully logged in.",
+        "status": "success"
+      }
+
+    - error on login
+
+    .. sourcecode:: http
+
+      HTTP/1.1 404 NOT FOUND
+      Content-Type: application/json
+
+      {
+        "message": "Invalid credentials.",
+        "status": "error"
+      }
+
+    :<json string email: user email
+    :<json string password_conf: password confirmation
+
+    :statuscode 200: Successfully logged in.
+    :statuscode 404: Invalid credentials.
+    :statuscode 500: Error. Please try again or contact the administrator.
+
+    """
     # get post data
     post_data = request.get_json()
     if not post_data:
@@ -135,7 +233,48 @@ def login_user():
 @auth_blueprint.route('/auth/logout', methods=['GET'])
 @authenticate
 def logout_user(user_id):
-    """ user logout """
+    """
+    user logout
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+      GET /auth/logout HTTP/1.1
+      Content-Type: application/json
+
+    **Example responses**:
+
+    - successful logout
+
+    .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "message": "Successfully logged out.",
+        "status": "success"
+      }
+
+    - error on login
+
+    .. sourcecode:: http
+
+      HTTP/1.1 401 UNAUTHORIZED
+      Content-Type: application/json
+
+      {
+        "message": "Provide a valid auth token.",
+        "status": "error"
+      }
+
+    :reqheader Authorization: OAuth 2.0 Bearer Token
+
+    :statuscode 200: Successfully logged out.
+    :statuscode 401: Provide a valid auth token.
+
+    """
     # get auth token
     auth_header = request.headers.get('Authorization')
     if auth_header:
@@ -164,7 +303,51 @@ def logout_user(user_id):
 @auth_blueprint.route('/auth/profile', methods=['GET'])
 @authenticate
 def get_user_status(user_id):
-    """ get authenticated user info """
+    """
+    get authenticated user info
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+      GET /auth/profile HTTP/1.1
+      Content-Type: application/json
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "data": {
+          "admin": false,
+          "bio": null,
+          "birth_date": null,
+          "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
+          "email": "admin@example.com",
+          "first_name": null,
+          "id": 2,
+          "last_name": null,
+          "location": null,
+          "nb_activities": 6,
+          "nb_sports": 3,
+          "picture": false,
+          "timezone": "Europe/Paris",
+          "total_distance": 67.895,
+          "total_duration": "6:50:27",
+          "username": "sam"
+        },
+        "status": "success"
+      }
+
+    :reqheader Authorization: OAuth 2.0 Bearer Token
+
+    :statuscode 200: success.
+    :statuscode 401: Provide a valid auth token.
+
+    """
     user = User.query.filter_by(id=user_id).first()
     response_object = {
         'status': 'success',
@@ -176,7 +359,64 @@ def get_user_status(user_id):
 @auth_blueprint.route('/auth/profile/edit', methods=['POST'])
 @authenticate
 def edit_user(user_id):
-    """ edit authenticated user """
+    """
+    edit authenticated user
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+      POST /auth/profile/edit HTTP/1.1
+      Content-Type: application/json
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "data": {
+          "admin": false,
+          "bio": null,
+          "birth_date": null,
+          "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
+          "email": "admin@example.com",
+          "first_name": null,
+          "id": 2,
+          "last_name": null,
+          "location": null,
+          "nb_activities": 6,
+          "nb_sports": 3,
+          "picture": false,
+          "timezone": "Europe/Paris",
+          "total_distance": 67.895,
+          "total_duration": "6:50:27",
+          "username": "sam"
+        },
+        "status": "success"
+      }
+
+    :<json string first_name: user first name
+    :<json string last_name: user last name
+    :<json string location: user location
+    :<json string bio: user biography
+    :<json string birth_date: user birth date (format: ``%Y-%m-%d``)
+    :<json string password: user password
+    :<json string password_conf: user password confirmation
+    :<json string timezone: user time zone
+
+    :reqheader Authorization: OAuth 2.0 Bearer Token
+
+    :statuscode 200: User profile updated.
+    :statuscode 400:
+        - Invalid payload.
+        - Password and password confirmation don't match.
+    :statuscode 401: Provide a valid auth token.
+    :statuscode 500: Error. Please try again or contact the administrator.
+
+    """
     # get post data
     post_data = request.get_json()
     if not post_data:
@@ -242,7 +482,59 @@ def edit_user(user_id):
 @auth_blueprint.route('/auth/picture', methods=['POST'])
 @authenticate
 def edit_picture(user_id):
-    """ update authenticated user picture """
+    """
+    update authenticated user picture
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+      POST /auth/picture HTTP/1.1
+      Content-Type: multipart/form-data
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: application/json
+
+      {
+        "data": {
+          "admin": false,
+          "bio": null,
+          "birth_date": null,
+          "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
+          "email": "admin@example.com",
+          "first_name": null,
+          "id": 2,
+          "last_name": null,
+          "location": null,
+          "nb_activities": 6,
+          "nb_sports": 3,
+          "picture": false,
+          "timezone": "Europe/Paris",
+          "total_distance": 67.895,
+          "total_duration": "6:50:27",
+          "username": "sam"
+        },
+        "status": "success"
+      }
+
+    :form file: image file (allowed extensions: .jpg, .png, .gif)
+
+    :reqheader Authorization: OAuth 2.0 Bearer Token
+
+    :statuscode 200: User picture updated.
+    :statuscode 400:
+        - Invalid payload.
+        - No file part.
+        - No selected file.
+        - File extension not allowed.
+    :statuscode 401: Provide a valid auth token.
+    :statuscode 500: Error during picture update.
+
+    """
     code = 400
     response_object = verify_extension('picture', request)
     if response_object['status'] != 'success':
@@ -293,7 +585,30 @@ def edit_picture(user_id):
 @auth_blueprint.route('/auth/picture', methods=['DELETE'])
 @authenticate
 def del_picture(user_id):
-    """ delete authenticated user picture """
+    """
+    delete authenticated user picture
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+      DELETE /auth/picture HTTP/1.1
+      Content-Type: application/json
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+      HTTP/1.1 204 NO CONTENT
+      Content-Type: application/json
+
+    :reqheader Authorization: OAuth 2.0 Bearer Token
+
+    :statuscode 204: picture deleted
+    :statuscode 401: Provide a valid auth token.
+    :statuscode 500: Error during picture deletion.
+
+    """
     try:
         user = User.query.filter_by(id=user_id).first()
         picture_path = get_absolute_file_path(user.picture)