Improve authentication documentation

app/assets/data/swagger.yaml

@@ -18,6 +18,16 @@ tags:
   - name: imports
     description: Bulk-importing Versions
 
+securityDefinitions:
+  BasicAuth:
+    type: basic
+  # Technically this should be "bearerAuth", but this is Swagger 2, and that's
+  # only supported in OpenAPI (Swagger 3).
+  ApiKeyAuth:
+    type: apiKey
+    in: header
+    name: Authorization
+
 parameters:
   sort:
     name: sort
@@ -95,7 +105,7 @@ paths:
           description: >-
             If true, add an `earliest` key to each page with the earliest version of it. (Note this is not affected by `capture_time`, which only modifies which *pages* are returned.)
           required: false
-          type: string
+          type: boolean
           default: false
         - name: include_latest
           in: query
@@ -1421,6 +1431,96 @@ paths:
           schema:
             $ref: '#/definitions/SingleTag'
 
+  '/users/sign_in':
+    post:
+      tags:
+        - authentication
+      summary: Sign in with user credentials
+      description: >
+        Get a session token to use for authenticating future requests by signing
+        in with this route. You can then use the returned token in future
+        requests instead of storing and sending user credentials.
+
+        To use the token in future requests, set the `Authorization` HTTP
+        header to `Bearer <token>`.
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - name: body
+          in: body
+          description: >
+            The request body should be a JSON object with a `user` property
+            containing `email` and `password` properties.
+          required: true
+          schema:
+            type: object
+            properties:
+              user:
+                type: object
+                required: true
+                properties:
+                  email:
+                    type: string
+                    format: email
+                    required: true
+                  password:
+                    type: string
+                    required: true
+      responses:
+        '200':
+          description: Successful Login
+          schema:
+            type: object
+            properties:
+              user:
+                $ref: '#/definitions/User'
+              token:
+                type: string
+                description: >
+                  Session token to use in `Authorization` header for future
+                  requests.
+        '401':
+          description: Invalid Credentials
+
+  '/users/session':
+    get:
+      tags:
+        - authentication
+      summary: Validate existing session token/credentials
+      description: >
+        If you have a session token, cookies, or credentials, you can check
+        whether they are valid and get information about the logged-in user by
+        requesting this endpoint and providing the credentials as you normally
+        would for any other API endpoint (as HTTP Basic authorization, as
+        cookies, or as setting the token in the `Authorization: Bearer <token>`
+        header).
+
+        If the session is still valid, the response will include information
+        about the logged-in user. If not, the response will be a JSON object
+        with a 401 status code.
+      produces:
+        - application/json
+      responses:
+        '200':
+          description: Successful Login
+          schema:
+            type: object
+            properties:
+              user:
+                $ref: '#/definitions/User'
+        '401':
+          description: Invalid Credentials
+          schema:
+            type: object
+            properties:
+              status:
+                type: integer
+                const: 401
+              title:
+                type: string
+
 definitions:
   Version:
     type: object
@@ -2027,6 +2127,29 @@ definitions:
         type: object
         description: Any additional metadata that you'd like to store. Typically, this is things like unique IDs from the source system (e.g. the site/page/version ID in Versionista), headers, content lengths, redirect chains, etc. The intent is that you should store as rich a set of metadata as you can get for every version, and this gives you a space to put all the information that we can't guarantee must be available from every type of source.
 
+  User:
+    type: object
+    properties:
+      id:
+      email:
+        type: string
+        format: email
+      created_at:
+        type: string
+        format: datetime
+      updated_at:
+        type: string
+        format: datetime
+      permissions:
+        type: array
+        items:
+          type: string
+          enum:
+            - view
+            - annotate
+            - import
+            - manage_users
+
 externalDocs:
   description: Find out more about the web-monitoring project.
   url: 'https://github.com/edgi-govdata-archiving/web-monitoring'

app/views/home/index.html.erb

@@ -5,22 +5,28 @@
 
 <div id="auth-notice">
   <p>
-    <strong>AUTHENTICATION:</strong> All endpoints currently require authenication.
-    We plan to make some endpoints public in the future, but the timeline is not yet known.
+    <strong>AUTHENTICATION:</strong> All GET endpoints can be accessed without
+    authentication, but some parameters (which might cause complex or
+    time-consuming queries) require authentication, as well as all
+    POST/PATCH/DELETE endpoints that change data.
   </p>
   <p>
-    You can authenticate a request by providing an e-mail and password with <strong>HTTP Basic authentication</strong> or, if you are authorizing a session on behalf of a user, exchanging an e-mail and password for a session token by POSTing a JSON object that matches the following structure to <code>/users/sign_in</code>:
-  </p>
-  <pre class="code-block">{
-  "user": {
-    "email": "someone@example.com",
-    "password": "someones_password"
-  }
-}</pre>
-  <p>
-    Make sure to set the <code>Accept</code> HTTP header to <code>application/json</code>.
-    The token will be the <code>token</code> property in the response JSON.
+    You can authenticate a request in 2 ways:
   </p>
+  <ol>
+    <li>
+      By providing an e-mail and password with <strong>HTTP Basic
+      authentication</strong> or
+    </li>
+    <li>
+      Including a session token in the <code>Authorization</code> header with
+      the value <code>Bearer: &lt;token&gt;</code>. Use this if you are
+      authorizing a session on behalf of a user. You can obtain a session
+      token at <code>/users/sign_in</code>; See the
+      <a href="#operations-tag-authentication">authentication section</a>
+      below for details.
+    </li>
+  <ol>
 </div>
 
 <div id="swagger-ui"></div>

config/routes.rb

@@ -12,6 +12,14 @@
 
   namespace :api do
     namespace :v0 do
+      # Add minimal login/session validation routes inside API namespace. These
+      # are the same as the root `/users/*` routes listed above. This is to
+      # make things easier for API clients (everything has the same base path).
+      devise_scope :user do
+        post 'users/sign_in', to: '/users/sessions#create'
+        get 'users/session', to: '/users/sessions#validate_session'
+      end
+
       resources :pages, only: [:index, :show], format: :json do
         get 'versions/sampled', to: 'versions#sampled'
         resources :versions, only: [:index, :show, :create]