doc: clarify using fleet api has lots of drawbacks

CHANGELOG.md

@@ -37,6 +37,8 @@
 - doc: add steps to the guide regarding how to switch to Fleet API (#4103 - @yangiak)
 - doc: align TPMS Pressure naming in sensor config to match ui config for home assistant (#4104 - @helmo)
 - doc: Update screenshots and rearrange links (#4151 - @jheredianet)
+- doc: fix markdownlint warnings in fleet api documentation (#4173 - @JakobLichterfeld)
+- doc: clarify using fleet api has lots of drawbacks (#4173 - @JakobLichterfeld)
 
 ## [1.30.1] - 2024-07-10
 

website/docs/guides/api.md

@@ -1,26 +1,30 @@
 ---
-title: Using the Official Tesla Fleet API and Telemetry Streaming
+title: Using the Tesla Fleet API and Telemetry Streaming (only for business fleet users)
 ---
 
 ## Official Tesla APIs
 
-### Why Tesla Fleet and Telemetry are Needed
+### Why Tesla Fleet and Telemetry only have drawbacks
 
-By default, TeslaMate uses the _unofficial_ Owner API and streaming.
+As far as we know, using the Tesla Fleet API and Telemetry API as a user has only drawbacks. The only reason to use them is if you are a Tesla Business Fleet user and therefore the Owner API is no longer available for you.
 
-Tesla now provides official APIs: the Fleet API and the Telemetry API, which replace the Owner API and streaming respectively.
+### When Tesla Fleet API and Telemetry API are needed
+
+By default, TeslaMate uses the "_unofficial_" Owner API and streaming.
+
+Tesla now provides official APIs: the Fleet API and the Telemetry API, which replace the Owner API and streaming respectively. But come with limitations and drawbacks.
 
 **Migration to the new API depends on your Tesla account type:**
 
 1. **_[Tesla Business Fleet users](https://www.tesla.com/fleet):_** the Owner API is [being shut down](https://developer.tesla.com/docs/fleet-api#2024-03-26-shutting-down-legacy-vehicle-api-endpoints). Fleet vehicles are upgraded gradually and an error message means that they must now use the official API.
 
-1. **_Individual users:_** the Owner API is currently still accessible. Even if it seems to incorporate new limitations similar to those present on the official API.
+2. **_Individual users:_** the Owner API is currently still accessible.
 
-**Resume: if you are a Tesla Business Fleet user, you should migrate to the official API ASAP!** The official Tesla API will only become mandatory when the Owner API shuts down for all users.
+**Resume: if you are a Tesla Business Fleet user, you should migrate to the official API ASAP!** The official Tesla API will only become mandatory when the Owner API shuts down for all users. Until then you can and should continue to use the Owner API, as it is more feature-rich and has higher resolution streaming.
 
 ### Impacts/Limitations of New Endpoints
 
-#### Tesla Fleet API: no impact
+#### Tesla Fleet API: very limited recording resolution
 
 The [Fleet API](https://developer.tesla.com/docs/fleet-api) is similar to the Owner API but more comprehensive. However, retrieving vehicle information (`vehicle_data`) or sending commands is limited. The limits on the Owner API were historically much higher. It is likely that [these limits](https://developer.tesla.com/docs/fleet-api#membership-levels) will also be applied soon to the API Owner.
 
@@ -59,11 +63,13 @@ MyTeslaMate also provides streaming by [reproducing the old streaming from the d
 
 1. You need to "_Pair your vehicle(s)_" on the [fleet](https://app.myteslamate.com/fleet) page
 1. Use the following dedicated environment variables:
+
    ```yml
    - TESLA_WSS_HOST=wss://streaming.myteslamate.com
    - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true
    - TESLA_WSS_USE_VIN=true
    ```
+
 1. Restart your instance
 
 ### [Teslemetry](https://teslemetry.com/pricing) (paid)
@@ -72,12 +78,14 @@ MyTeslaMate also provides streaming by [reproducing the old streaming from the d
 
 1. Log in the [Teslemetry website](https://teslemetry.com) and create your `TOKEN`.
 1. Use this `TOKEN` instead of _`xxxx-xxxx-xxxx-xxxx`_ and add the following environment variables:
+
    ```yml
    - TOKEN=?token=xxxx-xxxx-xxxx-xxxx
    - TESLA_API_HOST=https://api.teslemetry.com
    - TESLA_AUTH_HOST=https://api.teslemetry.com
    - TESLA_AUTH_PATH=/api/oauth2/v3
    ```
+
 1. Restart your instance
 
 #### Teslemetry Streaming
@@ -97,22 +105,24 @@ MyTeslaMate also provides streaming by [reproducing the old streaming from the d
 1. Set up a third-party account at [developer.tesla.com](https://developer.tesla.com) as described on the [Tesla docs](https://developer.tesla.com/docs/fleet-api#setup)
 1. Add the following environment variable with your own domain :
       1. Use [the correct region](https://developer.tesla.com/docs/fleet-api#endpoints-and-regional-requirements) in the `TESLA_API_HOST` field:
-         - North America, Asia-Pacific (excluding China): https://fleet-api.prd.na.vn.cloud.tesla.com
-         - Europe, Middle East, Africa: https://fleet-api.prd.eu.vn.cloud.tesla.com
-         - China: https://fleet-api.prd.cn.vn.cloud.tesla.cn 
+         - North America, Asia-Pacific (excluding China): [https://fleet-api.prd.na.vn.cloud.tesla.com](https://fleet-api.prd.na.vn.cloud.tesla.com)
+         - Europe, Middle East, Africa: [https://fleet-api.prd.eu.vn.cloud.tesla.com](https://fleet-api.prd.eu.vn.cloud.tesla.com)
+         - China: [https://fleet-api.prd.cn.vn.cloud.tesla.cn](https://fleet-api.prd.cn.vn.cloud.tesla.cn)
       1. Update the `TESLA_AUTH_CLIENT_ID` with the client ID of your Tesla application.
+
    ```yml
    # API Fleet
    - TESLA_API_HOST=https://fleet-api.prd.eu.vn.cloud.tesla.com
    - TESLA_AUTH_HOST=https://auth.tesla.com
    - TESLA_AUTH_PATH=/oauth2/v3
    - TESLA_AUTH_CLIENT_ID=xxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx
    ```
+
 1. (Optional) If you want to send commands or use Tesla Telemetry:
    1. Send drivers a "Pairing request" to be able to use your own [Tesla Vehicle Command Protocol http proxy to send commands](https://github.com/teslamotors/vehicle-command?tab=readme-ov-file#using-the-http-proxy)
-   1. Send test commands or setup Telemetry to [stream it to your Teslamate](#streaming-via-tesla-telemetry)
+   2. Send test commands or setup Telemetry to [stream it to your Teslamate](#streaming-via-tesla-telemetry)
 
-#### Switching from Owners API to Fleet API 
+#### Switching from Owners API to Fleet API
 
 1. Sign out from the current Owners API by visiting the teslamate settings page
 2. Follow step 1&2 from [Tesla Fleet API](https://docs.teslamate.org/docs/guides/api#tesla-fleet-api)
@@ -130,11 +140,13 @@ To setup your own streaming server, you can follow these steps:
 1. Setup a [MyTeslaMate Streaming Server from Fleet Telemetry Events](https://github.com/MyTeslaMate/websocket) on a public domain (eg: _streaming.mydomain.com_)
 1. Manually create a subscription to the `telemetry_V` created in PubSub by the Tesla Telemetry with:
    - Delivery type: Push
-   - Endpoint URL: https://streaming.mydomain.com
+   - Endpoint URL: [https://streaming.mydomain.com](https://streaming.mydomain.com)
 1. Update your environment variables:
+
    ```yml
    - TESLA_WSS_HOST=wss://streaming.mydomain.com
    - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true
    - TESLA_WSS_USE_VIN=true
    ```
+
 1. Restart your instance