|
| 1 | +--- |
| 2 | +id: api |
| 3 | +title: API Usage |
| 4 | +--- |
| 5 | + |
| 6 | +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. |
| 7 | + |
| 8 | +**Please note:** HackathonManager's primary audience is the web interface. |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +## Endpoints |
| 13 | + |
| 14 | +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)). |
| 15 | + |
| 16 | +For example, listing bus lists: |
| 17 | + |
| 18 | +- User-facing page: https://apply.brickhack.io/manage/bus_lists |
| 19 | +- API endpoint: https://apply.brickhack.io/manage/bus_lists.json |
| 20 | + |
| 21 | +Because Rails follows a standard CRUD-format, these endpoints become very REST-like. |
| 22 | + |
| 23 | +For example: |
| 24 | + |
| 25 | +- List all tags: `GET https://apply.brickhack.io/manage/trackable_tags.json` |
| 26 | +- View specific tag: `GET https://apply.brickhack.io/manage/trackable_tags/1.json` |
| 27 | +- Create tag: `POST https://apply.brickhack.io/manage/trackable_tags.json` (with a JSON body of parameters) |
| 28 | +- Update tag: `PATCH https://apply.brickhack.io/manage/trackable_tags/1.json` (with a JSON body of parameters) |
| 29 | +- Delete tag: `DELETE https://apply.brickhack.io/manage/trackable_tags/1.json` |
| 30 | + |
| 31 | +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). |
| 32 | + |
| 33 | +**Note: datatable endpoints** are highly coupled to [Datatables](https://datatables.net) functionality and are not easy to use. |
| 34 | + |
| 35 | +Example for questionnaire management endpoints: |
| 36 | + |
| 37 | +``` |
| 38 | +... |
| 39 | + Prefix Verb URI Pattern Controller#Action |
| 40 | + datatable_manage_questionnaires POST /manage/questionnaires/datatable(.:format) manage/questionnaires#datatable |
| 41 | + check_in_manage_questionnaire PATCH /manage/questionnaires/:id/check_in(.:format) manage/questionnaires#check_in |
| 42 | + convert_to_admin_manage_questionnaire PATCH /manage/questionnaires/:id/convert_to_admin(.:format) manage/questionnaires#convert_to_admin |
| 43 | +update_acc_status_manage_questionnaire PATCH /manage/questionnaires/:id/update_acc_status(.:format) manage/questionnaires#update_acc_status |
| 44 | + bulk_apply_manage_questionnaires PATCH /manage/questionnaires/bulk_apply(.:format) manage/questionnaires#bulk_apply |
| 45 | + message_events_manage_questionnaire GET /manage/questionnaires/:id/message_events(.:format) manage/questionnaires#message_events |
| 46 | + manage_questionnaires GET /manage/questionnaires(.:format) manage/questionnaires#index |
| 47 | + POST /manage/questionnaires(.:format) manage/questionnaires#create |
| 48 | + new_manage_questionnaire GET /manage/questionnaires/new(.:format) manage/questionnaires#new |
| 49 | + edit_manage_questionnaire GET /manage/questionnaires/:id/edit(.:format) manage/questionnaires#edit |
| 50 | + manage_questionnaire GET /manage/questionnaires/:id(.:format) manage/questionnaires#show |
| 51 | + PATCH /manage/questionnaires/:id(.:format) manage/questionnaires#update |
| 52 | + PUT /manage/questionnaires/:id(.:format) manage/questionnaires#update |
| 53 | + DELETE /manage/questionnaires/:id(.:format) manage/questionnaires#destroy |
| 54 | + datatable_manage_checkins POST /manage/checkins/datatable(.:format) |
| 55 | +... |
| 56 | +``` |
| 57 | + |
| 58 | +## Request & response |
| 59 | + |
| 60 | +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. |
| 61 | + |
| 62 | +Note that while most endpoints support JSON responses, some do not have this support. Redirect responses are common for some actions, for which you'll receive a 302 redirect response and no JSON body. |
| 63 | + |
| 64 | +The best way to see what's expected is to look at the controller source code, located at [`app/controllers/`](https://github.com/codeRIT/hackathon_manager/tree/master/app/controllers). Here, you'll see how each endpoint is configured; this maps to the routes listed by `bin/rails routes`. For example: |
| 65 | + |
| 66 | +```ruby |
| 67 | +def show |
| 68 | + respond_with(:manage, @questionnaire) |
| 69 | +end |
| 70 | +``` |
| 71 | + |
| 72 | +- This "show" endpoint is the natural mapping for something like `GET /manage/questionnaires/1.json` |
| 73 | +- Because `respond_with` is used, it will return JSON when `.json` is used in the URL |
| 74 | + |
| 75 | +# Authentication |
| 76 | + |
| 77 | +Authentication is implemented with OAauth 2, provided by the [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) gem. |
| 78 | + |
| 79 | +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. |
| 80 | + |
| 81 | +For Doorkeeper endpoints + docs, see https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples |
| 82 | + |
| 83 | +Once appropriate authentication credentials are retrieved, they should be provided on all API requests. |
| 84 | + |
| 85 | +### Security note |
| 86 | + |
| 87 | +For a mobile- or front-end app, or any app that has API calls running on the client, you should **not** use an authorization flow involving the application secret; otherwise, you would be distributing the secret to the public, compromising the whitelist nature of controlling which apps may pose as your users. |
| 88 | + |
| 89 | +For most use cases, the **authorization code grant** or **implicit grant** flows should be used. Check out [this guide by Auth0](https://auth0.com/docs/api-auth/which-oauth-flow-to-use) for more info. |
0 commit comments