Merge pull request #22 from ECN/update-docs

Update docs
ECN · Apr 4, 2021 · ecbfbd6 · ecbfbd6
2 parents a5a185d + 651da82
commit ecbfbd6
Show file tree

Hide file tree

Showing 16 changed files with 1,123 additions and 702 deletions.
diff --git a/docs/api/API Overview.md b/docs/api/API Overview.md
diff --git a/docs/api/Authentication.md b/docs/api/Authentication.md
@@ -2,6 +2,7 @@
 
 The webqueue2 API uses a two stage authentication system combining Active Directory and [HTTP Token](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) (or "bearer") authentication.
 
+## Getting an Access Token
 All API calls require an access token. You can get an access token by making a POST request to the `/api/login` endpoint containing the JSON encoded username and password of a valid user.
 
 ??? info "Who is a valid user?"
@@ -11,66 +12,68 @@ All API calls require an access token. You can get an access token by making a P
     - `00000227-ECNStuds`
     - `00000227-ECN-webqueue-misc`
 
-=== "fetch"
-    ```javascript
-    const accessToken = (async _ => {
-        const loginInit = {
-            method: "POST",
-            headers: {'Content-Type': 'application/json'},
-            body: JSON.stringify({ "username": USERNAME, "password": PASSWORD})
-        };
+### Example
+!!! example "Get an access token."
+
+    ```js
+    {% include 'api/get_access_token.js' %}
+    ```
+    ```js
+    // Expected Output
+    "{{ example_access_token }}"
+    ```
 
-        let loginResponse = await fetch("API_URL/api/login", loginInit);
-        let data = await loginResponse.json();
+## Making Calls With Access Token
+To interact with the API, add an `Authorization` header to your request with a value of `Bearer TOKEN` where `TOKEN` is your access token. 
 
-        if (data === null){
-            return false;
-        }
+### Example: 
+!!! example "Get item CE 100."
+    ```js
+    let access_token = "{{ example_access_token }}";
+    let queue = "ce";
+    let item_number = 100;
 
-        if (!loginResponse.ok){
-            console.error(`Login failed. Got code ${loginResponse.status} (${loginResponse.statusText})`);
-            return false;
-        }
-
-        return data.access_token || false;
-    })();
+    fetch(
+        `https://engineering.purdue.edu/webqueue/webqueue2/build/api/data/${queue}/${item_number}`,
+        { headers: {"Authorization":`Bearer ${access_token}` }}
+    )
+    .then( resp => resp.json() )
+    .then( data => console.log( data ));
     ```
-
-=== "cURL"
-    !!! warning
-        It is **strongly** recomended to store and retrieve your login credentials in a [cURL config file](https://everything.curl.dev/cmdline/configfile) that only your user can read to avoid exposing your credentials to your shell history or the host process table.
-
-    Create a cURL config file named `wq2_login.config`:
-    ```bash
-    nano ~/wq_login.config
+    ```js
+    // Expected Output
+    {queue: "ce", number: 100, lastUpdated: "2021-03-11T07:24:00-0500" ... }
     ```
 
-    Add the cURL options:
-    ```python
-    # ~/wq_login.config
-    request = POST
-    header = "Content-Type: application/json"
-    data = {"username":"USERNAME","password":"PASSWORD"}
-    url = "API_URL/api/login"
-    ```
+## Refreshing Access Tokens
+When you login, you'll receive an access token that expires 15 minutes after creation as well as two cookies needed to get a new access token. Those cookies are:
 
-    Restrict read permissions to your user:
-    ```bash
-    chmod 700 ~/wq_login.config
-    ```
-
-    Run cURL using your new config file:
-    ```bash
-    curl -K ~/wq_login.config
-    ```
-    ```
-    # Expected Output:
-    {"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MTYxODI1MjMsIm5iZiI6MTYxNjE4MjUyMywianRpIjoiYzI2ZjY4NDctZGU2OC00ODUzLWI4ODctMTBmZDAyMDcyY2U0IiwiZXhwIjoxNjE2MTgzNDIzLCJzdWIiOiJjYW1wYjMwMyIsImZyZXNoIjpmYWxzZSwidHlwZSI6ImFjY2VzcyIsImNzcmYiOiJjYjYzZWE1My1jOWQ2LTQ5YTItYmZhMi0wY2U4N2Q3YzcxZDcifQ.T7bezsOMreMCXWR0R5w5BKI673hpOquCOnvT1XkyDjY"}
-    ```
+Name | Value | Path | Expiration | SameSite
+-- | -- | -- | -- | --
+`refresh_token_cookie` | Your refresh token. | `/api/tokens/refresh` | 30 Days | Yes
+`csrf_refresh_token` | Additional verification data. (e.g. `{{ example_csrf_token }}`) | `/` | Session | Yes
+
+The `refresh_token_cookie` is used to generate a new access token and will be sent back to the server with every request automatically. It expires 30 days after login. The `csrf_refresh_token` is used to verify the `refresh_token_cookie` and needs sent back as an `X-CSRF-TOKEN` header. 
 
-    ??? tip "Tip for Parsing Tokens in Bash"
-        You can parse the access token using Python like this:
-        ```bash
-        curl -K ~/wq_login.config | \
-            python3 -c "import sys, json; print(json.load(sys.stdin)['access_token'])"
-        ```
+To refresh your access token, make a POST request to the `/api/tokens/refresh` endpoint with the value of the `csrf_refresh_token` cookies inside a `X-CSRF-TOKEN` header:
+
+### Example
+!!! example "Get a new refresh token."
+    ```js
+    // Get this value from your cookies.
+    const csrf_refresh_token = "{{ example_csrf_token }}"
+
+    fetch(
+        `{{ production_url }}/api/tokens/refresh`,
+        {
+            method: "POST",
+            headers: {'X-CSRF-TOKEN': csrf_refresh_token}
+        }
+    )
+    .then( resp => resp.json() )
+    .then( data => console.log( data.access_token ));
+    ```
+    ```js
+    // Expected Output
+    {{ example_access_token }}
+    ```
diff --git a/docs/api/Getting Started.md b/docs/api/Getting Started.md
@@ -2,26 +2,41 @@
 
 The webqueue2 API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). The API has resource oriented URLs, accepts and returns JSON encoded request bodies, can be modified via the query string and uses standard HTTP response codes and verbs.
 
+You can use the webqueue2 API hosted at [{{ production_url }}/api]({{ production_url }}/api) or [install it on your own machine](Installation.md).
+
 ## Basic Usage
 
-!!! example "Get the number of Items in a Queue"
-    === "fetch"
-        ```javascript
-        ()();
-        ```
+!!! example "Get the first item in CE queue."
+    ```javascript
+    let access_token = "{{ example_access_token }}";
+    let queue = "ce";
 
-    === "cURL"
-        ```bash
-        curl -K
-        ```
+    fetch(
+        `https://engineering.purdue.edu/webqueue/webqueue2/build/api/data/${queue}`,
+        { headers: {"Authorization":`Bearer ${access_token}` }}
+    )
+    .then( resp => resp.json() )
+    .then( data => console.log( data[0].items[0] ));
+    ```
+    ```js
+    // Expected Output
+    { queue: "ce", number: 17, lastUpdated: "2021-03-29T17:12:00-0400" ... }
+    ```
 
-!!! example "Get the subject of an Item"
-    === "fetch"
-        ```javascript
-        console.log
-        ```
+!!! example "Get the subject of an CE 1."
+    ```javascript
+    let access_token = "{{ example_access_token }}";
+    let queue = "ce";
+    let item_number = 1;
 
-    === "cURL"
-        ```bash
-        curl -K
-        ```
+    fetch(
+        `https://engineering.purdue.edu/webqueue/webqueue2/build/api/data/${queue}/${item_number}`,
+        { headers: {"Authorization":`Bearer ${access_token}` }}
+    )
+    .then( resp => resp.json() )
+    .then( data => console.log( data.subject ));
+    ```
+    ```js
+    // Expected Output
+    "Linux Server Purchase"
+    ```