feat: integration with VATSIM API Core v2 (#828)

Partially solves #808 by integrating VATSIM API Core v2 support. Co-authored-by: Daniel <[email protected]>
Vatsim-Scandinavia · Mar 6, 2024 · b3ba08a · b3ba08a
1 parent 321cb28
commit b3ba08a
Show file tree

Hide file tree

Showing 7 changed files with 162 additions and 61 deletions.
diff --git a/.env.example b/.env.example
@@ -11,10 +11,6 @@ APP_TRACKING_SCRIPT=
 APP_LOGO="vatsca.svg"
 APP_LOGO_MAIL="vatsca-email.png"
 
-VATSIM_DIVISION_API_DRIVER="VATEUD"
-VATSIM_DIVISION_API_URL=""
-VATSIM_DIVISION_API_TOKEN=""
-
 DEBUGBAR_ENABLED=false
 LOG_CHANNEL=stack
 
@@ -30,9 +26,15 @@ OAUTH_ID=
 OAUTH_SECRET=
 OAUTH_URL="https://auth-dev.vatsim.net"
 
+VATSIM_CORE_API_TOKEN=
+
 VATSIM_BOOKING_API_URL=
 VATSIM_BOOKING_API_TOKEN=
 
+VATSIM_DIVISION_API_DRIVER="VATEUD"
+VATSIM_DIVISION_API_URL=""
+VATSIM_DIVISION_API_TOKEN=""
+
 SENTRY_LARAVEL_DSN=null
 SENTRY_TRACES_SAMPLE_RATE=0.1
 

diff --git a/CONFIGURE.md b/CONFIGURE.md
@@ -15,35 +15,36 @@ Here is a list over all environment variables you may tweak. You may start the c
 
 Table with all the variables, default value and explanation. Override the environment variable to change the value if the default value does not fit your needs.
 
-| Variable | Default value | Explanation |
-| ------- | --- | --- |
-| APP_NAME | Control Center | Name of your subdivision |
-| APP_OWNER | Subdivision Name | Name of your subdivision |
-| APP_OWNER_SHORT | SCA | Usually 3 letter name identifying your vACC within VATSIM API |
-| APP_URL | http://localhost | URL to your Control Center |
-| APP_ENV | production | Environment of your Control Center |
-| DB_CONNECTION | mysql | Database connection type |
-| DB_HOST | localhost | Database host |
-| DB_PORT | 3306 | Database port |
-| DB_DATABASE | control-center | Database name |
-| DB_USERNAME | root | Database username |
-| DB_PASSWORD | root | Database password |
-| DB_TABLE_PREFIX | null | Database table prefix |
-| OAUTH_URL | https://auth.vatsim.net | OAuth URL of VATSIM |
-| OAUTH_ID | null | OAuth ID of your subdivision |
-| OAUTH_SECRET | null | OAuth secret of your subdivision |
-| VATSIM_API_TOKEN | null | Token to VATSIM API |
-| VATSIM_BOOKING_API_URL | https://atc-bookings.vatsim.net/api | URL to VATSIM Booking API |
-| VATSIM_BOOKING_API_TOKEN | null | Token to VATSIM Booking API |
-| MAIL_MAILER | smtp | Mailer type |
-| MAIL_HOST | smtp.mailgun.org | Mail host |
-| MAIL_PORT | 587 | Mail port |
-| MAIL_USERNAME | null | Mail username |
-| MAIL_PASSWORD | null | Mail password |
-| MAIL_ENCRYPTION | null | Mail encryption |
-| MAIL_FROM_NAME | Control Center | Mail from name |
-| MAIL_FROM_ADDRESS | [email protected] | Mail from address |
-| TRUSTED_PROXIES | null | Comma-separated list of trusted proxy addresses or '*' for all |
+| Variable                 | Default value                       | Explanation                                                                                            |
+|--------------------------|-------------------------------------|--------------------------------------------------------------------------------------------------------|
+| APP_NAME                 | Control Center                      | Name of your subdivision                                                                               |
+| APP_OWNER                | Subdivision Name                    | Name of your subdivision                                                                               |
+| APP_OWNER_SHORT          | SCA                                 | Usually 3 letter name identifying your vACC within VATSIM API                                          |
+| APP_URL                  | http://localhost                    | URL to your Control Center                                                                             |
+| APP_ENV                  | production                          | Environment of your Control Center                                                                     |
+| DB_CONNECTION            | mysql                               | Database connection type                                                                               |
+| DB_HOST                  | localhost                           | Database host                                                                                          |
+| DB_PORT                  | 3306                                | Database port                                                                                          |
+| DB_DATABASE              | control-center                      | Database name                                                                                          |
+| DB_USERNAME              | root                                | Database username                                                                                      |
+| DB_PASSWORD              | root                                | Database password                                                                                      |
+| DB_TABLE_PREFIX          | null                                | Database table prefix                                                                                  |
+| OAUTH_URL                | https://auth.vatsim.net             | OAuth URL of VATSIM                                                                                    |
+| OAUTH_ID                 | null                                | OAuth ID of your subdivision                                                                           |
+| OAUTH_SECRET             | null                                | OAuth secret of your subdivision                                                                       |
+| VATSIM_API_TOKEN         | null                                | API token (v1) to VATSIM API **(Obsolete: Use VATSIM Core API instead. VATSIM do not issue v1 keys.**) |
+| VATSIM_CORE_API_TOKEN    | null                                | API token (v2) to VATSIM Core API                                                                      |
+| VATSIM_BOOKING_API_URL   | https://atc-bookings.vatsim.net/api | URL to VATSIM ATC Bookings API                                                                         |
+| VATSIM_BOOKING_API_TOKEN | null                                | API Token to VATSIM ATC Bookings API                                                                   |
+| MAIL_MAILER              | smtp                                | Mailer type                                                                                            |
+| MAIL_HOST                | smtp.mailgun.org                    | Mail host                                                                                              |
+| MAIL_PORT                | 587                                 | Mail port                                                                                              |
+| MAIL_USERNAME            | null                                | Mail username                                                                                          |
+| MAIL_PASSWORD            | null                                | Mail password                                                                                          |
+| MAIL_ENCRYPTION          | null                                | Mail encryption                                                                                        |
+| MAIL_FROM_NAME           | Control Center                      | Mail from name                                                                                         |
+| MAIL_FROM_ADDRESS        | [email protected]                | Mail from address                                                                                      |
+| TRUSTED_PROXIES          | null                                | Comma-separated list of trusted proxy addresses or '*' for all                                         |
 
 #### OAuth
 
@@ -101,7 +102,7 @@ docker exec -it control-center sh container/theme/build.sh
 ### Optional: Extras
 
 | Variable | Default value | Explanation |
-| ------- | --- | --- 
+| ------- | --- | ---
 | APP_DEBUG | false | Toggle debug mode of your Control Center |
 | APP_TRACKING_SCRIPT | null | Input javascript here with your tracking script, e.g. Google Analytics |
 | DEBUGBAR_ENABLED | false | Toggle debug bar of your Control Center |
@@ -117,7 +118,7 @@ Here you find the diffrerent data tables which need to be edited to suit your su
 ### Areas
 In `Areas` table, create one or more areas. This is something student select between when applying for trianing.
 | id | name | contact | template_newreq | template_newmentor | template_pretraining | feedback_url |
-| ------- | --- | --- | --- |  --- |  --- | --- | 
+| ------- | --- | --- | --- |  --- |  --- | --- |
 | x | Name | Contact e-mail that will be displayed to students | Can be set in Notification Editor, set NULL | Same as last | Same as last | URL to feedback form shown in training completed email |
 | 1 | Norway | [email protected] | NULL | NULL | NULL | https://forms.gle/your-feedback-form |
 ### Ratings
@@ -143,5 +144,3 @@ In `positions` table, we define which positions are possible to book and their r
 | x | The callsign | Name of position showed when booking | optional frequency, not used inside CC for now | Used for filtering in bookings | id of area | vatsim rating id required to book position | Is this a endorsement position?
 | 1 | ENBR_TWR | Flesland Tower | NULL | ENOR | 4 | 3 | NULL
 | 2 | ENGM_TWR | Gardermoen Tower | NULL | ENOR | 4 | 3 | 1
-
-
diff --git a/app/Http/Controllers/UserController.php b/app/Http/Controllers/UserController.php
@@ -34,23 +34,38 @@ public function index()
     {
         $this->authorize('index', \Auth::user());
 
-        $response = $this->fetchApiUsers();
-        if ($response === false) {
-            $users = [];
+        $users = [];
 
-            return view('user.index', compact('users'))->withErrors('Error fetching users from VATSIM API. Check if your token is correct.');
+        if (config('vatsim.core_api_token')) {
+            $response = $this->fetchUsersFromVatsimCoreApi();
+            if ($response === false) {
+                return view('user.index', compact('users'))->withErrors('Error fetching users from VATSIM Core API. Check if your token is correct.');
+            }
+        } else if (config('vatsim.api_token')) {
+            $response = $this->fetchUsersFromVatsimApi();
+            if ($response === false) {
+                return view('user.index', compact('users'))->withErrors('Error fetching users from VATSIM API. Check if your token is correct.');
+            }
+        } else {
+            return view('user.index', compact('users'))->withErrors('Enable VATSIM Core API Integration to enable this feature.');
         }
 
         $apiUsers = [];
         $ccUsers = User::pluck('id');
         $ccUsersHours = AtcActivity::all();
         $ccUsersActive = User::getActiveAtcMembers()->pluck('id');
 
-        // Only include users from the division and index by key
-        foreach ($response as $data) {
-            if ($data['subdivision'] == config('app.owner_code')) {
+        if (config('vatsim.core_api_token')) {
+            foreach ($response as $data) {
                 $apiUsers[$data['id']] = $data;
             }
+        } else {
+            // Only include users from the division and index by key
+            foreach ($response as $data) {
+                if ($data['subdivision'] == config('app.owner_code')) {
+                    $apiUsers[$data['id']] = $data;
+                }
+            }
         }
 
         // Merge the data sources
@@ -421,19 +436,61 @@ public function extendWorkmail()
         }
     }
 
+    /**
+     * Fetch users from VATSIM Core API
+     *
+     * @return \Illuminate\Http\Response|bool
+     */
+    private function fetchUsersFromVatsimCoreApi()
+    {
+        $url = sprintf('https://api.vatsim.net/v2/orgs/subdivision/%s', config('app.owner_short'));
+        $headers = [
+            'X-API-Key' => config('vatsim.core_api_token'),
+            'Accept' => 'application/json',
+            'Content-Type' => 'application/json',
+        ];
+
+        $users = [];
+        $usersCount = 0;
+
+        $limit = 1000;
+        $count = -1;
+
+        do {
+            $response = Http::withHeaders($headers)->get(sprintf('%s?include_inactive=1&limit=%s&offset=%s', $url, $limit, $usersCount));
+
+            if (! $response->successful()) {
+                return false;
+            }
+
+            $jsonResponse = $response->json();
+
+            if ($count == -1) {
+                $count = $jsonResponse['count'];
+            }
+
+            $users = array_merge($users, $jsonResponse['items']);
+            $usersCount = count($users);
+        } while ($usersCount < $count);
+
+        return $users;
+    }
+
     /**
      * Fetch users from VATSIM API
      *
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\Response|bool
      */
-    private function fetchApiUsers()
+    private function fetchUsersFromVatsimApi()
     {
-        $url = 'https://api.vatsim.net/api/subdivisions/' . config('app.owner_code') . '/members/';
-        $response = Http::withHeaders([
+        $url = sprintf('https://api.vatsim.net/api/subdivisions/%s/members/', config('app.owner_code'));
+        $headers = [
             'Authorization' => 'Token ' . config('vatsim.api_token'),
             'Accept' => 'application/json',
             'Content-Type' => 'application/json',
-        ])->get($url);
+        ];
+
+        $response = Http::withHeaders($headers)->get($url);
 
         if (! $response->successful()) {
             return false;

diff --git a/config/vatsim.php b/config/vatsim.php
@@ -5,6 +5,9 @@
     /*
     |--------------------------------------------------------------------------
     | VATSIM API
+    |
+    | This is the configuration for the VATSIM API integration.
+    | This is used to configure the secrets.
     |--------------------------------------------------------------------------
     |
     */
@@ -13,10 +16,22 @@
 
     /*
     |--------------------------------------------------------------------------
-    | Booking API Integration
+    | VATSIM Core API
+    |
+    | This is the configuration for the VATSIM Core API integration.
+    | This is used to configure the secrets.
+    |--------------------------------------------------------------------------
+    |
+    */
+
+    'core_api_token' => env('VATSIM_CORE_API_TOKEN', null),
+
+    /*
+    |--------------------------------------------------------------------------
+    | VATSIM ATC Bookings API Integration
     |--------------------------------------------------------------------------
     |
-    | This is the configuration for the booking API integration.
+    | This is the configuration for the VATSIM ATC Bookings API integration.
     | This is used to configure the secrets and endpoints.
     |
     */

diff --git a/docs/concepts/booking.md b/docs/concepts/booking.md
@@ -11,7 +11,7 @@ This feature is an integral part of the training, examination and event experien
 
 - **No Time Restrictions**: Control Center does not enforce time limits on bookings; these are managed at the division or subdivision level.
 - **Mutually Exclusive Tags**: The booking overview help ensure clarity and purpose in bookings with mutually exclusive tags.
-- **Integration with VATSIM**: Our system seamlessly integrates with the [VATSIM ATC Booking API](../integrations/vatsim.md), enhancing interoperability with other websites and ATC roster overviews.
+- **Integration with VATSIM**: Our system seamlessly integrates with the [VATSIM ATC Bookings API](../integrations/vatsim.md), enhancing interoperability with other websites and ATC roster overviews.
 - **Programmatic Bookings**: In addition to manual bookings, our system [supports automated bookings](../api.md), such as those created for event staffing through Discord bots.
 
 ## For All ATC Members

diff --git a/docs/configuration/index.md b/docs/configuration/index.md
@@ -66,11 +66,12 @@ Settings related to configuring OAuth-based authentication adhering to the field
 
 Settings related to the [VATSIM integration](../integrations/vatsim.md).
 
-| Variable | Default value | Explanation |
-| ------- | --- | --- |
-| `VATSIM_API_TOKEN` | null | Token to VATSIM API |
-| `VATSIM_BOOKING_API_URL` | `https://atc-bookings.vatsim.net/api` | URL to VATSIM Booking API |
-| `VATSIM_BOOKING_API_TOKEN` | null | Token to VATSIM Booking API |
+| Variable                   | Default value                         | Explanation                                                                                            |
+|----------------------------|---------------------------------------|--------------------------------------------------------------------------------------------------------|
+| `VATSIM_API_TOKEN`         | null                                  | API token (v1) to VATSIM API **(Obsolete: Use VATSIM Core API instead. VATSIM do not issue v1 keys.**) |
+| `VATSIM_CORE_API_TOKEN`    | null                                  | API token (v2) to VATSIM Core API                                                                      |
+| `VATSIM_BOOKING_API_URL`   | `https://atc-bookings.vatsim.net/api` | URL to VATSIM ATC Bookings API                                                                         |
+| `VATSIM_BOOKING_API_TOKEN` | null                                  | API token to VATSIM ATC Bookings API                                                                   |
 
 ### Mail
 

diff --git a/docs/integrations/vatsim.md b/docs/integrations/vatsim.md
@@ -2,9 +2,36 @@
 
 There's no Control Center without VATSIM.
 
-Besides supporting [VATSIM Connect](./vatsim-connect.md), Control Center relies on the [VATSIM ATC Bookings][vatsim-bookings] to support bookings.
+Besides supporting [VATSIM Connect](./vatsim-connect.md), Control Center relies on:
 
-Control Center uses [the central booking API][vatsim-bookings-api] to [get, publish, edit and remove controller bookings](../concepts/booking.md).
+ * [VATSIM API][vatsim-api]
+ * [VATSIM Core API][vatsim-core-api]
+ * [VATSIM ATC Bookings API][vatsim-atc-bookings-api]
 
-  [vatsim-bookings]: https://atc-bookings.vatsim.net
-  [vatsim-bookings-api]: https://atc-bookings.vatsim.net/api-doc
+!!! tip "Use VATSIM APIs with Control Center"
+    See [the configuration manual](../configuration/index.md#vatsim) to get started.
+
+## VATSIM API
+
+[VATSIM API][vatsim-api] is used to retrieve public user data. It can be used to retrieve members of a subdivision, but it is preferred to use [VATSIM Core API][vatsim-core-api] for this task as this approach is deprecated and will be removed in the future.
+
+!!! info
+    VATSIM API key v1 is required to enable this feature. If you don't have this key already, you need to ask VATSIM Tech Department for a v2 key for Core API instead as they're not handing out v1 anymore.
+
+## VATSIM Core API
+
+[VATSIM Core API][vatsim-core-api] is used to retrieve members of a subdivision.
+
+!!! info
+    VATSIM Core API key v2 is required to enable this feature, contact VATSIM Tech Department using VATSIM Support to get your key.
+
+## VATSIM ATC Bookings API
+
+[VATSIM ATC Bookings API][vatsim-atc-bookings-api] is used get, publish, edit and remove controller bookings.
+
+!!! info
+    VATSIM ATC Bookings API key is required to enable this feature, contact VATSIM Tech Department using VATSIM Support to get your key.
+
+[vatsim-api]: https://api.vatsim.net/api/
+[vatsim-core-api]: https://vatsim.dev/api/core-api
+[vatsim-atc-bookings-api]: https://atc-bookings.vatsim.net/api-doc