API overview ¶

Shift and invitation branch work uses the Laravel API authentication base to build on. The goal is to merge the use in these branches and to use /api endpoints for more front-end work as more UI is moved to vuejs or similar components.

https://laravel.com/docs/5.8/api-authentication

Migrations were added to add an api_token to user table and a trait to add an api_token to each new user record when created.

The api_token is added to a window.laravel object via a small javascript block on the main app.blade file. It can be referenced as window.laravel.api_token.

In the bootstrap.js file, the token is automatically added as the Bearer authentication token on an axios handler. The axios handler also sets /api as a default path. The axios handler is added as a global

axios.get("/shifts")

The code above will call /api/shifts with the bearer token for the currently logged in user.

routing ¶

The standard api.php route file is used at this time.

versioning ¶

There are a few different approaches to expressing and processing an API version call.

There isn’t a firm decision on which particular path to choose at this point; options 1 and 2 both err on the side of explicitness, which is likely a better foundation to build on longer term, although there may be some other option which would allow for some dynamic ‘fallback’ while allowing for explicit overrides as needed.

As with other aspects of development, testing around endpoint usage will allow for making routing modifications (when needed) with confidence.

/tests/ShiftApiTest.php has example calls demonstrating the three options below.

Option 1 ¶

Route::middleware('auth:api')->get('/shifts', 'Api\ShiftController@shifts')->defaults('version',1)->name('api_shifts');

Route::middleware('auth:api')->get('/v2/shifts', 'Api\ShiftController@shifts')->defaults('version',2)->name('api_shifts');

public function shifts(Request $request, $version = 1)

The “defaults” will pass a $version value to the controller method, indicating the API version call. The controller method can pass the version flag to calls as needed and/or make decisions directly if necessary.

Option 2 ¶

Route::middleware('auth:api')->get('/v2/shifts', 'Api\V2\ShiftController@shifts')->defaults('version',2)->name('api_shifts');

In this case, we’re routing a /v2 call to an explicit V2 namespaced controller, which could extend from the base/v1 ShiftController, only modifying necessary methods.

Option 3 ¶

Route::middleware('auth:api')->get('/v{version}/shifts', 'Api\ShiftController@shifts')->defaults('version',1)->name('api_shifts');

In this case, the ‘version’ is parsed from the route itself, and passed along to the controller methods.

Oct 2020 update ¶

Reintroducing use of /api endpoints for use by vetportal js/vue code. This will allow for longer-lived use of the vetportal screens without issues of session timeouts creating bad state.

With all requests going through standard ‘web’ auth guard relying on standard web session, session timeouts would mean that endpoints calls may break. Better error handling would help resolve some of the confusion, but the end user experience expects long-term use of the system - clock in at 8am, clock out at 5:30pm, and users do not expect to have to re-authenticate.

Extending session time would mean that all users would have extended sessions - not horrible, but for hospital managers, that can present a slight risk elevation.

Additionally, ‘web’ auth guard uses VerifyCSRFToken filter, and CSRF tokens would be lost with session-based work. Some code still relies on ‘plain’ session state, so leaving that alone for ‘earlier’ code makes more sense. Early work added multiple expections to VerifyCSRFToken check - most of those are being removed.

Two pieces are modified in October 2020 API move.

reintroducing /api auth guard
forcing ‘dr’ user “remember me” option on login

The ‘remember me’ will reauthenticate a user whose session has been logged out. It will also create a new session, so the CSRF token issue was still a problem. The long-lived user interaction use case is candidate for /api auth guard for these endpoints.
These may all end be being renamed under a /vetportal path for easier indentification in future. There are some similar routes that are /ajax (web), not /api, and these may be renamed in a future push.

11/9/20 - trigger rebuild