diff --git a/.gitignore b/.gitignore index 3ec128763..1cfa93888 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,6 @@ /.idea .generators + +# macOS +.DS_Store \ No newline at end of file diff --git a/docs/api-setup.md b/docs/api-setup.md new file mode 100644 index 000000000..64cc522c2 --- /dev/null +++ b/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. + + + +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: + + + +Then, click the `Get Access Token` button. + +On this screen, fill out the information but with your own keys from the image above. + + + +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`: + + + +You should see this resulting screen. On here, select `Use Token`: + + + +That's it! Now you can make authorized requests at whatever permission level your account has. + + + +## Connecting with Paw + +The process is very similar to above. To save time, here is a screenshot of the `auth` config screen: + + + +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`). diff --git a/docs/api.md b/docs/api-usage.md similarity index 69% rename from docs/api.md rename to docs/api-usage.md index 924e4b005..374a3cc87 100644 --- a/docs/api.md +++ b/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. diff --git a/docs/assets/api-setup/authorize.png b/docs/assets/api-setup/authorize.png new file mode 100644 index 000000000..57db52799 Binary files /dev/null and b/docs/assets/api-setup/authorize.png differ diff --git a/docs/assets/api-setup/doorkeeper.png b/docs/assets/api-setup/doorkeeper.png new file mode 100644 index 000000000..43203d19b Binary files /dev/null and b/docs/assets/api-setup/doorkeeper.png differ diff --git a/docs/assets/api-setup/paw1.png b/docs/assets/api-setup/paw1.png new file mode 100644 index 000000000..66c77e12d Binary files /dev/null and b/docs/assets/api-setup/paw1.png differ diff --git a/docs/assets/api-setup/postman1.png b/docs/assets/api-setup/postman1.png new file mode 100644 index 000000000..b984eb5dc Binary files /dev/null and b/docs/assets/api-setup/postman1.png differ diff --git a/docs/assets/api-setup/postman2.png b/docs/assets/api-setup/postman2.png new file mode 100644 index 000000000..798de56e6 Binary files /dev/null and b/docs/assets/api-setup/postman2.png differ diff --git a/docs/assets/api-setup/postman3.png b/docs/assets/api-setup/postman3.png new file mode 100644 index 000000000..01c8fb0ae Binary files /dev/null and b/docs/assets/api-setup/postman3.png differ diff --git a/docs/assets/api-setup/postman4.png b/docs/assets/api-setup/postman4.png new file mode 100644 index 000000000..cad8abdf3 Binary files /dev/null and b/docs/assets/api-setup/postman4.png differ diff --git a/docs/assets/api-setup/postman5.png b/docs/assets/api-setup/postman5.png new file mode 100644 index 000000000..d15161e54 Binary files /dev/null and b/docs/assets/api-setup/postman5.png differ diff --git a/website/sidebars.json b/website/sidebars.json index 80c51de0a..782f15584 100755 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,7 +1,7 @@ { "docs": { "HackathonManager": ["running-a-hackathon", "busses", "questionnaires", "messages"], - "API Usage": ["api"], + "API": ["api-setup", "api-usage"], "Deployment": [ "deployment", "deployment-dokku",