docs: Add guide for local API setup, update api-usage slightly (#235)

* docs: Add API/OAuth 2 setup guide

Also rename api to api-usage

* docs: Cleanup api-usage page, add notes about 2.0

* docs: Apply suggestions from code review

Co-authored-by: Stuart Olivera <stuart@stuartolivera.com>

* docs: Reword API introduction to be more friendly

- Clarifies what Postman and Paw are, with links to their product pages
- Notes that this process works for remote instances as well, not just localhost
- Removed trailing whitespace and extra newlines
- Fixed a single typo

* Verbiage and HM typo fixes

* Added .DS_Store to .gitignore

Co-authored-by: Stuart Olivera <stuart@stuartolivera.com>

Author: peterkos

.gitignore

@@ -33,3 +33,6 @@
 /.idea
 
 .generators
+
+# macOS
+.DS_Store

docs/api-setup.md

@@ -0,0 +1,70 @@
+---
+id: api-setup
+title: Setup Postman/Paw for API Testing
+---
+
+This page will show you how to simulate API requests with [Postman](https://www.postman.com/) or [Paw](https://paw.cloud/).
+
+These programs allow you to run API requests (`GET`, `POST`, and so on) in an isolated environment, which is much easier to debug in compared to an iOS or Android app, for example.
+
+In order to make requests in either Postman or Paw, you need to setup _OAuth 2 authorization_, as in HackathonManager, each request needs to be authorized first. This guide discusses how to enable OAuth 2 for these apps.
+
+This guide assumes you have already setup an admin account on a local HackathonManager instance. For more details on this, see the [main README](https://github.com/codeRIT/hackathon-manager#local-development).
+
+> To make API requests on a live/remote instance, simply replace `localhost` in all following commands with your HackathonManager's URL.
+
+Select an app below to jump directly to its guide:
+
+- [Connecting with Postman](#initial-setup-with-postman)
+- [Connecting with Paw](#initial-setup-with-paw)
+
+## OAuth2 Notes
+
+- The application only supports `Authorization Code` and `Implicit Grant` authorization methods. It's suggested to use an `implicit` grant for native apps, as they are inherently trusted.
+- In a real application, the callback URL should have a specific scope that's not just `http://`, i.e., `brickhack-ios://` (for BrickHack's iOS application). However Postman would really be confused with that scheme, so for local development, it's not advised.
+- Client credentials must be sent in the body.
+- Browser authorization is currently not supported, at least in Postman. Not sure why! If you discover a reason, please open an Issue on the [Hackathon Manager](https://github.com/codeRIT/hackathon-manager) repo.
+
+## Connecting with Postman
+
+In HackathonManager, sign in to your admin account and click "Manage". Then, at the bottom left of the sidebar, click the **Doorkeeper** tab.
+
+<img src="assets/api-setup/doorkeeper.png" width="300px" />
+
+On this screen, click `New Application`.
+
+Name it whatever you wish. Set the Redirect URI to `http://localhost:3000/apply`, uncheck `Confidential`, and set a scope to `main`. Then, click `Submit`.
+
+> Note: There is [a bug](https://github.com/doorkeeper-gem/doorkeeper/issues/1307) in the current version of doorkeeper (5.0), where if you do not put a scope, all OAuth requests fail. This scope can be anything as long as it is not empty.
+
+Now, go to Postman and configure the initial request as follows:
+
+<img src="assets/api-setup/postman1.png" width="500px" />
+
+Then, click the `Get Access Token` button.
+
+On this screen, fill out the information but with your own keys from the image above.
+
+<img src="assets/api-setup/postman2.png" width="500px" />
+
+You should get a popup with your hackathon's sign in screen. Type in your admin credentials and log in.
+
+On the next screen, select `Authorize`:
+
+<img src="assets/api-setup/postman3.png" width="500px" />
+
+You should see this resulting screen. On here, select `Use Token`:
+
+<img src="assets/api-setup/postman4.png" width="600px" />
+
+That's it! Now you can make authorized requests at whatever permission level your account has.
+
+<img src="assets/api-setup/postman5.png" />
+
+## Connecting with Paw
+
+The process is very similar to above. To save time, here is a screenshot of the `auth` config screen:
+
+<img src="assets/api-setup/paw1.png" />
+
+To reset your login, remove the dynamic fields in `Refresh Token` and `Token`. If your web login is still cached, try clearing cookies (`Paw > Web Views > Clear Cookies`) and Cache (`Paw > Web Views > Clear Cache`).

docs/api.md renamed to docs/api-usage.md

@@ -1,41 +1,43 @@
 ---
-id: api
+id: api-usage
 title: API Usage
 ---
 
-Almost all of the functionality exposed to users can also be accessed as an API with OAuth credentials. This includes both public- and management-facing functionality.
+## Introduction
 
-**Please note:** HackathonManager's primary audience is the web interface.
+Almost all of the functionality exposed to users can also be accessed as an API with OAuth credentials. This includes both public and management-facing functionality.
 
-While functionality may co-exist for both browser and API usage, API-style support might be a little rough around some edges. If you stumble upon something that works a little different than usual (e.g. returns HTML instead of JSON), open an issue and we can figure it out.
+**Please note:** HackathonManager's primary audience is the web interface. The API is currently being rewritten to support more application-based functionality, however this is still a work in progress, and not all functions will be supported on version `2.0`.
 
-## Endpoints
+If you run into any inconsistencies, feel free to open an issue on the [hackathon-manager](https://github.com/codeRIT/hackathon-manager) repo.
 
-Endpoints are shared with regular page controllers for browser-style functionality. This leverages Ruby on Rails routing (for a deep dive, see [Rails Routing from the Outside In](https://guides.rubyonrails.org/routing.html)).
+## Endpoints
 
-For example, listing bus lists:
+> Note that endpoints are currently being rewritten to support more user-based access, rather than hiding most information under an admin-level restriction.
 
-- User-facing page: https://apply.brickhack.io/manage/bus_lists
-- API endpoint: https://apply.brickhack.io/manage/bus_lists.json
+Endpoints are shared with regular page controllers for browser-style functionality. This leverages Ruby on Rails routing (for a deep dive, see [Rails Routing from the Outside In](https://guides.rubyonrails.org/routing.html)).
 
 Because Rails follows a standard CRUD-format, these endpoints become very REST-like.
 
 For example:
 
-- List all tags: `GET https://apply.brickhack.io/manage/trackable_tags.json`
-- View specific tag: `GET https://apply.brickhack.io/manage/trackable_tags/1.json`
-- Create tag: `POST https://apply.brickhack.io/manage/trackable_tags.json` (with a JSON body of parameters)
-- Update tag: `PATCH https://apply.brickhack.io/manage/trackable_tags/1.json` (with a JSON body of parameters)
-- Delete tag: `DELETE https://apply.brickhack.io/manage/trackable_tags/1.json`
+|       Action      |                                             Reuqest                                              |
+|-------------------|--------------------------------------------------------------------------------------------------|
+| List all tags     | `GET https://your-hackathon.io/manage/trackable_tags.json`                                      |
+| View specific tag | `GET https://your-hackathon.io/manage/trackable_tags/1.json`                                    |
+| Create tag        | `POST https://your-hackathon.io/manage/trackable_tags.json` (with body parameters)              |
+| Update tag        | `PATCH https://your-hackathon.io/manage/trackable_tags/1.json` (with body parameters) |
+| Delete tag        | `DELETE https://your-hackathon.io/manage/trackable_tags/1.json`                                 |
 
 For a full list of endpoints, run `bin/rails routes` locally. This utility, provided by Ruby on Rails, lists all possible paths you can route too (along with their respective HTTP method).
 
-**Note: datatable endpoints** are highly coupled to [Datatables](https://datatables.net) functionality and are not easy to use.
+> Note: Datatable endpoints are highly coupled to [Datatables](https://datatables.net) functionality and are not easy to use.
+
+> Note: The following endpoints are currently being rewritten to allow for less restrictions, i.e., bypassing the `/manage/`-level permission.
 
 Example for questionnaire management endpoints:
 
 ```
-...
                                 Prefix Verb     URI Pattern                                              Controller#Action
        datatable_manage_questionnaires POST     /manage/questionnaires/datatable(.:format)               manage/questionnaires#datatable
          check_in_manage_questionnaire PATCH    /manage/questionnaires/:id/check_in(.:format)            manage/questionnaires#check_in
@@ -52,10 +54,9 @@ update_acc_status_manage_questionnaire PATCH    /manage/questionnaires/:id/updat
                                        PUT      /manage/questionnaires/:id(.:format)                     manage/questionnaires#update
                                        DELETE   /manage/questionnaires/:id(.:format)                     manage/questionnaires#destroy
              datatable_manage_checkins POST     /manage/checkins/datatable(.:format)
-...
 ```
 
-## Request & response
+## Request & Response
 
 Most endpoints can operate with JSON requests & responses. Simply provide `.json` at the end of the URL to be returned JSON, and provide `Content-Type: application/json` when using POST or PATCH with a JSON body.
 
@@ -72,13 +73,11 @@ end
 - This "show" endpoint is the natural mapping for something like `GET /manage/questionnaires/1.json`
 - Because `respond_with` is used, it will return JSON when `.json` is used in the URL
 
-# Authentication
-
-Authentication is implemented with OAauth 2, provided by the [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) gem.
+## Authentication
 
-An OAuth app should be created by an admin at https://apply.your-hackathon.com/oauth/applications. From there, you can implement a standard OAuth 2 flow.
+Authentication is implemented with OAauth 2, provided by the [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) gem. For full Doorkeeper endpoints + docs, see the [Doorkeeper wiki](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples).
 
-For Doorkeeper endpoints + docs, see https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples
+See the [Setup Postman/Paw for API Testing](api-setup.md) page for information on using those tools for testing the API locally.
 
 Once appropriate authentication credentials are retrieved, they should be provided on all API requests.