From d5f573d3905e9b00b30eb0b945e163c16660eb33 Mon Sep 17 00:00:00 2001 From: Justin Campbell Date: Thu, 1 Apr 2021 22:39:16 -0400 Subject: [PATCH] Remove cURL examples, simplify javascript examples --- docs/api/Authentication.md | 177 ++++++++----------------------------- 1 file changed, 38 insertions(+), 139 deletions(-) diff --git a/docs/api/Authentication.md b/docs/api/Authentication.md index 7097641..15a097d 100644 --- a/docs/api/Authentication.md +++ b/docs/api/Authentication.md @@ -12,105 +12,41 @@ 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 - {% include 'api/get_access_token.js' %} - ``` - -=== "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 - ``` - - Add the cURL options: - ```python - # ~/wq_login.config - request = POST - header = "Content-Type: application/json" - data = {"username":"USERNAME","password":"PASSWORD"} - url = "{{ production_url }}/api/login" - # Save cookies for future API calls - cookies = "wq_cookies" - ``` - - Restrict read permissions to your user: - ```bash - chmod 700 ~/wq_login.config - ``` +### Example +!!! example "Get an access token." - Run cURL using your new config file: - ```bash - curl -K ~/wq_login.config - ``` + ```js + {% include 'api/get_access_token.js' %} ``` - # Expected Output: - {"access_token": "{{ example_access_token }}"} + ```js + // Expected Output + "{{ example_access_token }}" ``` - ??? 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'])" - ``` - ## 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. -Example: Get item `ce100` -=== "fetch" - ```javascript - const ce100 = (async _ => { - const loginInit = { - method: "GET", - headers: {'Authentication': 'Bearer {{ example_access_token }}'}, - }; - - let apiResponse = await fetch("{{ production_url }}/api/data/ce/100", loginInit); - let data = await apiResponse.json(); - - if (data === null){ - return false; - } +### Example: +!!! example "Get item `ce100`" + ```js + let access_token = "{{ example_access_token }}"; + let queue = "ce"; + let item_number = 100; - if (!apiResponse.ok){ - console.error(`Fetching item ce100 failed. Got code ${apiResponse.status} (${apiResponse.statusText})`); - return false; - } - - return data || 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" - Create a cURL config file named `wq_get_ce100.config`: - ```bash - nano ~/wq_get_ce100.config - ``` - - Set cURL options - ```python - # ~/wq_get_ce100.config - request = GET - header = "Authorization: Bearer {{ example_access_token }}" - url = "{{ production_url }}/api/data/ce/100" - ``` - - Run cURL using your new config file: - ```bash - curl -K ~/wq_get_ce100.config - ``` - ``` - # Expected Output: - { 'assignedTo': 'campb303', 'building': '', 'content': [...], 'dateReceived': '2020-06-23T13:25:51-0400', 'department': '', 'headers': [...], 'isLocked': 'ce 100 is locked by knewell using qvi', 'lastUpdated': '2020-12-01T19:53:00-0500', 'number': 100, 'priority': '', 'queue': 'ce', 'status': 'Dont Delete', 'subject': 'Beepboop', 'userAlias': 'campb303', 'userEmail': 'campb303@purdue.edu', 'userName': 'Justin Campbell' } + ```js + // Expected Output + {queue: "ce", number: 100, lastUpdated: "2021-03-11T07:24:00-0500" ... } ``` ## Refreshing Access Tokens -By default, access tokens expire 15 minutes after being issued and need refreshed. During login, you'll receive two cookies: +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: Name | Value | Path | Expiration | SameSite -- | -- | -- | -- | -- @@ -121,60 +57,23 @@ The `refresh_token_cookie` is used to generate a new access token and will be se 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: -=== "fetch" - ```javascript - const newAccessToken = (async _ => { - const csrf_refresh_token = some_func_to_get_csrf_token_cookie(); +### Example +!!! example "Get a new refresh token." + ```js + // Get this value from your cookies. + const csrf_refresh_token = "{{ example_csrf_token }}" - const refreshInit = { + fetch( + `{{ production_url }}/api/tokens/refresh`, + { method: "POST", - headers: {'X-CSRF-TOKEN': csrf_refresh_token}, - }; - - let refreshResponse = await fetch(`{{ production_url }}/api/tokens/refresh`, refreshInit); - let data = await refreshResponse.json(); - - if (data === null){ - return false; + headers: {'X-CSRF-TOKEN': csrf_refresh_token} } - if (!refreshResponse.ok){ - console.error(`Refresh failed. Got code ${refreshResponse.status} (${refreshResponse.statusText})`); - return false; - } - - return data.access_token || false; - })(); + ) + .then( resp => resp.json() ) + .then( data => console.log( data.access_token )); ``` - -=== "cURL" - Create a cURL config file named `wq_refresh.config`: - ```bash - nano ~/wq_refresh.config - ``` - - Set cURL options - ```python - # ~/wq_refresh.config - request = POST - header = "X-CSRF-TOKEN: {{ example_csrf_token }}" - url = "{{ production_url }}/api/tokens/refresh" - # Pull cookies from login. - cookie-jar = "wq_cookies" - ``` - - Run cURL using your new config file: - ```bash - curl -K ~/wq_refresh.config - ``` - ``` - # Expected Output: - {"access_token": "{{ example_access_token }}"} - ``` - - ??? 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'])" - ``` + ```js + // Expected Output + {{ example_access_token }} ``` \ No newline at end of file