MEN-4107: introduce new chapter: Device-side API

- Rename 200.API to 200.Device-side-API - Introduce 201.Client-side-API - Rename 201.Troubleshoot to 301.Troubleshoot - Rename 202.Release-information to 302.Release-information - Fix links Changelog: title Signed-off-by: Fabio Tranchitella <[email protected]>
TheMeaningfulEngineer · Jun 2, 2021 · 843f438 · 843f438
1 parent c963c14
commit 843f438
Show file tree

Hide file tree

Showing 34 changed files with 80 additions and 54 deletions.
diff --git a/.checklinks-whitelist b/.checklinks-whitelist
@@ -1,16 +1,17 @@
 {
     "paths": [
-        "200.API"
+        "200.Server-side-API",
+        "200.Device-side-API"
     ],
     "files": [
-        "202.Release-information/01.Release-notes-changelog/10.Mender-server",
-        "202.Release-information/01.Release-notes-changelog/20.Mender-client",
-        "202.Release-information/01.Release-notes-changelog/21.mender-connect",
-        "202.Release-information/01.Release-notes-changelog/22.mender-configure-module",
-        "202.Release-information/01.Release-notes-changelog/30.mender-artifact",
-        "202.Release-information/01.Release-notes-changelog/31.mender-cli",
-        "202.Release-information/01.Release-notes-changelog/32.mender-convert",
-        "202.Release-information/01.Release-notes-changelog/40.meta-mender",
-        "202.Release-information/01.Release-notes-changelog/50.mender-binary-delta"
+        "302.Release-information/01.Release-notes-changelog/10.Mender-server",
+        "302.Release-information/01.Release-notes-changelog/20.Mender-client",
+        "302.Release-information/01.Release-notes-changelog/21.mender-connect",
+        "302.Release-information/01.Release-notes-changelog/22.mender-configure-module",
+        "302.Release-information/01.Release-notes-changelog/30.mender-artifact",
+        "302.Release-information/01.Release-notes-changelog/31.mender-cli",
+        "302.Release-information/01.Release-notes-changelog/32.mender-convert",
+        "302.Release-information/01.Release-notes-changelog/40.meta-mender",
+        "302.Release-information/01.Release-notes-changelog/50.mender-binary-delta"
     ]
 }
diff --git a/.passive-blacklist b/.passive-blacklist
@@ -1,6 +1,7 @@
 06.Artifact-creation
 07.Server-installation
 09.Downloads
-200.API
-201.Troubleshoot
-202.Release-information
+200.Server-side-API
+201.Device-side-API
+301.Troubleshoot
+302.Release-information
diff --git a/01.Get-started/01.Preparation/docs.md b/01.Get-started/01.Preparation/docs.md
@@ -68,5 +68,5 @@ Share and learn from other Mender users.
 
 * Learn more about Mender by reading the rest of the documentation, for example
 the [Overview](../../02.Overview/01.Introduction/docs.md),
-[Troubleshoot](../../201.Troubleshoot/) or
+[Troubleshoot](../../301.Troubleshoot/) or
 [Mender FAQ](https://mender.io/plans/faq?target=_blank) sections.
diff --git a/02.Overview/07.Identity/docs.md b/02.Overview/07.Identity/docs.md
@@ -39,7 +39,7 @@ Therefore, we do not recommend using device keys as part of an identity, as it
 makes the rotation or regeneration of keys over the lifetime of the device
 (as it in effect changes the identity) difficult.
 
-When a device requests [authentication](../../200.API/?target=_blank#default-device-authentication),
+When a device requests [authentication](../../200.Server-side-API/?target=_blank#default-device-authentication),
 it includes the identity attributes. The Mender server computes the persistent
 identity of the device based on these attributes.
 

diff --git a/02.Overview/13.Device-authentication/docs.md b/02.Overview/13.Device-authentication/docs.md
@@ -58,7 +58,7 @@ feature, leverages a PKI (Public Key Infrastructure) to authorize devices based
 client certificates without the need of explicit user's actions. Below is a detailed
 breakdown of each.
 
-For details of API calls please consult the [API documentation](../../200.API/?target=_blank#default-device-authentication).
+For details of API calls please consult the [API documentation](../../200.Server-side-API/?target=_blank#default-device-authentication).
 
 ### Authorize-on-request Flow
 
@@ -170,5 +170,5 @@ The token does have an **expiry date** (one week period by default), but the Men
 will obtain a fresh token from the Mender server automatically.
 
 For details on the token format please see the relevant [documentation on
-submitting an authentication request](../../200.API/?target=_blank#default-device-authentication).
+submitting an authentication request](../../200.Server-side-API/?target=_blank#default-device-authentication).
 
diff --git a/02.Overview/14.Compatibility/docs.md b/02.Overview/14.Compatibility/docs.md
@@ -89,7 +89,7 @@ In general the Mender client introduces new features in minor (e.g. 1.2.0 to 1.3
 !! <sup>2</sup> Rolling back to 1.x.x from a failed upgrade to 2.x.x is supported. However, it is not possible to downgrade to a Mender 1.x.x client from a 2.x.x client, once the update containing 2.x.x has been committed.
 
 <!--AUTOVERSION: "from % to newer"/ignore "from-%-to-newer"/ignore-->
-! <sup>3</sup> If upgrading from thud to newer versions, see also [known issues when upgrading from thud to newer versions](../../201.Troubleshoot/02.Yocto-Project-runtime/docs.md#upgrading-from-thud-to-newer-versions-fails-with-dual-rootfs-configuration-not-found).
+! <sup>3</sup> If upgrading from thud to newer versions, see also [known issues when upgrading from thud to newer versions](../../301.Troubleshoot/02.Yocto-Project-runtime/docs.md#upgrading-from-thud-to-newer-versions-fails-with-dual-rootfs-configuration-not-found).
 
 Leverage [Mender consulting services to support other versions of the Yocto Project](https://mender.io/product/board-support?target=_blank) for your board and environment.
 
@@ -123,7 +123,7 @@ The [Mender Artifact format](../03.Artifact/docs.md) is managed by the [Mender A
 
 ## Mender server and client API
 
-The compatibility between the Mender server and client is managed by the Device API versions exposed by the server and used by the client. If the Mender server supports the API version of the Mender client, they are compatible.  However, please ensure that the client and server support the [Artifact format](#mender-clientserver-and-artifact-format) version you are using. Device API docs are available in the [API chapter](../../200.API/?target=_blank#device-apis).
+The compatibility between the Mender server and client is managed by the Device API versions exposed by the server and used by the client. If the Mender server supports the API version of the Mender client, they are compatible.  However, please ensure that the client and server support the [Artifact format](#mender-clientserver-and-artifact-format) version you are using. Device API docs are available in the [API chapter](../../200.Server-side-API/?target=_blank#device-apis).
 
 <!--AUTOVERSION: "| %"/ignore-->
 |        | Mender server versions | Mender client versions |

diff --git a/03.Client-installation/04.Inventory/docs.md b/03.Client-installation/04.Inventory/docs.md
@@ -20,7 +20,7 @@ name0=value0\n
 .
 nameN=valueN\n
 ```
-The client reports the attributes via the [device inventory service API calls](../../200.API/?target=_blank#patch__device_attributes), by issuing **PATCH** _/device/attributes_.
+The client reports the attributes via the [device inventory service API calls](../../200.Server-side-API/?target=_blank#patch__device_attributes), by issuing **PATCH** _/device/attributes_.
 
 
 ### Lists of values

diff --git a/04.System-updates-Debian-family/01.Overview/docs.md b/04.System-updates-Debian-family/01.Overview/docs.md
@@ -55,7 +55,7 @@ Note that the default setup of systemd will use network time
 synchronization to maintain the clock in a running system. This may
 take a few minutes to stabilize on system boot so it is possible
 to have a few connection rejections from the server until this process
-is complete and the time is correct. Please see [certificate troubleshooting](../../201.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid) for more information about the symptoms of this issue.
+is complete and the time is correct. Please see [certificate troubleshooting](../../301.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid) for more information about the symptoms of this issue.
 
 If your device does not have an active internet connection, then systemd
 will be unable to configure the system time as it will be unable to connect

diff --git a/05.System-updates-Yocto-Project/01.Overview/docs.md b/05.System-updates-Yocto-Project/01.Overview/docs.md
@@ -70,7 +70,7 @@ Note that the default setup of systemd will use network time
 synchronization to maintain the clock in a running system. This may
 take a few minutes to stabilize on system boot so it is possible
 to have a few connection rejections from the server until this process
-is complete and the time is correct. Please see [certificate troubleshooting](../../201.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid) for more information about the symptoms of this issue.
+is complete and the time is correct. Please see [certificate troubleshooting](../../301.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid) for more information about the symptoms of this issue.
 
 If your device does not have an active internet connection, then systemd
 will be unable to configure the system time as it will be unable to connect

diff --git a/05.System-updates-Yocto-Project/03.Build-for-demo/docs.md b/05.System-updates-Yocto-Project/03.Build-for-demo/docs.md
@@ -67,7 +67,7 @@ the [Mender Consulting services to integrate your board](https://mender.io/suppo
 
 Make sure that the clock is set correctly on your devices. Otherwise certificate verification will become unreliable
 and **the Mender client can likely not connect to the Mender server**.
-See [certificate troubleshooting](../../201.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid) for more information.
+See [certificate troubleshooting](../../301.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid) for more information.
 
 
 ## Yocto Project

diff --git a/05.System-updates-Yocto-Project/06.Build-for-production/docs.md b/05.System-updates-Yocto-Project/06.Build-for-production/docs.md
@@ -40,7 +40,7 @@ server.
 
 !! Please make your device has the clock correctly set up. Otherwise certificate
 !! verification will become invalid. See
-!! [certificate troubleshooting](../../201.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid)
+!! [certificate troubleshooting](../../301.Troubleshoot/03.Mender-Client/docs.md#certificate-expired-or-not-yet-valid)
 !! for more information.
 
 

diff --git a/05.System-updates-Yocto-Project/99.Variables/docs.md b/05.System-updates-Yocto-Project/99.Variables/docs.md
@@ -648,7 +648,7 @@ The storage device, as referred to by U-Boot (e.g. `1`). This variable can be
 used in cases where the Linux kernel and U-Boot refer to the same device with
 different names. See [The bootloader and the Linux kernel do not agree about the
 indexes of storage
-devices](../../201.Troubleshoot/01.Yocto-project-build/docs.md#the-bootloader-and-the-linux-kernel-do-not-agree-about-the-indexes-of-storage-devices)
+devices](../../301.Troubleshoot/01.Yocto-project-build/docs.md#the-bootloader-and-the-linux-kernel-do-not-agree-about-the-indexes-of-storage-devices)
 for more information.
 
 If the variable is empty, it is automatically deduced from
@@ -663,7 +663,7 @@ The storage interface, as referred to by U-Boot (e.g. `mmc`). This variable can
 be used in cases where the Linux kernel and U-Boot refer to the same device with
 different names. See [The bootloader and the Linux kernel do not agree about the
 indexes of storage
-devices](../../201.Troubleshoot/01.Yocto-project-build/docs.md#the-bootloader-and-the-linux-kernel-do-not-agree-about-the-indexes-of-storage-devices)
+devices](../../301.Troubleshoot/01.Yocto-project-build/docs.md#the-bootloader-and-the-linux-kernel-do-not-agree-about-the-indexes-of-storage-devices)
 for more information.
 
 If the variable is empty, it is automatically deduced from

diff --git a/06.Artifact-creation/04.State-scripts/docs.md b/06.Artifact-creation/04.State-scripts/docs.md
@@ -104,7 +104,7 @@ Because of the possible re-execution described above, state scripts should be wr
 Mender captures the standard error (but not standard out) stream from
 state scripts. The standard error stream from state scripts is stored
 as part of the Mender deployment log, so it becomes available
-[locally on the client](../../201.Troubleshoot/03.Mender-Client/docs.md#deployment-log-files)
+[locally on the client](../../301.Troubleshoot/03.Mender-Client/docs.md#deployment-log-files)
 as well as reported to the server (if the deployment fails) to ease diagnostics.
 
 Thus the state scripts should be written so they output diagnostics

diff --git a/07.Server-installation/04.Certificates-and-keys/docs.md b/07.Server-installation/04.Certificates-and-keys/docs.md
@@ -20,11 +20,11 @@ for which purpose can be seen below.
 
 | Component               | Purpose of keys                                                                                                                                                                                                                                                                                                                  | Shares certificate or key with                                                                                                                |
 |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| API Gateway           | Listens to a public port for `https` requests only (plain `http` is disabled). These requests can come from Mender Clients that check for- or report status about updates through the [Device APIs](../../200.API/?target=_blank#device-apis), or from users and tools that manage deployments through the [Management APIs](../../200.API/?target=_blank#management-apis). | **Mender Clients** and users of the **Management APIs**, including web browsers accessing the **Mender UI**.                                       |
+| API Gateway           | Listens to a public port for `https` requests only (plain `http` is disabled). These requests can come from Mender Clients that check for- or report status about updates through the [Device APIs](../../200.Server-side-API/?target=_blank#device-apis), or from users and tools that manage deployments through the [Management APIs](../../200.Server-side-API/?target=_blank#management-apis). | **Mender Clients** and users of the **Management APIs**, including web browsers accessing the **Mender UI**.                                       |
 | Storage Proxy         | Listens to a public port for `https` requests only (plain `http` is disabled). The Deployment Service manages Artifacts through the Storage Proxy and Mender Clients make Artifact download requests.                                                                                                        | **Mender Clients** and **Deployment Service**.                                                                                                    |
-| User Administration   | Signs and verifies JSON Web Tokens that users of the [Management APIs](../../200.API/?target=_blank#management-apis), including end users of the Mender UI, include in their requests to authenticate themselves.                                                                                                                                     | Nothing. The service gets signature verification requests from the API Gateway, so all keys are kept private to the service and not shared. |
-| Device Authentication | Signs and verifies JSON Web Tokens that Mender Clients include in their requests to authenticate themselves when accessing the [Device APIs](../../200.API/?target=_blank#device-apis).                                                                                                                                                                   | Nothing. The service gets signature verification requests from the API Gateway, so all keys are kept private to the service and not shared. |
-| Mender Client | Signs requests for JSON Web Tokens sent to the Device Authentication service. A Mender Client will request a new token when it connects to the Mender Server for the first time, and when a token expires. The Mender Client includes a token in all its communication to authenticate itself when accessing the [Device APIs](../../200.API/?target=_blank#device-apis).                                                                                                                                                                   | The **Device Authentication** service stores the public keys of Mender Clients. |
+| User Administration   | Signs and verifies JSON Web Tokens that users of the [Management APIs](../../200.Server-side-API/?target=_blank#management-apis), including end users of the Mender UI, include in their requests to authenticate themselves.                                                                                                                                     | Nothing. The service gets signature verification requests from the API Gateway, so all keys are kept private to the service and not shared. |
+| Device Authentication | Signs and verifies JSON Web Tokens that Mender Clients include in their requests to authenticate themselves when accessing the [Device APIs](../../200.Server-side-API/?target=_blank#device-apis).                                                                                                                                                                   | Nothing. The service gets signature verification requests from the API Gateway, so all keys are kept private to the service and not shared. |
+| Mender Client | Signs requests for JSON Web Tokens sent to the Device Authentication service. A Mender Client will request a new token when it connects to the Mender Server for the first time, and when a token expires. The Mender Client includes a token in all its communication to authenticate itself when accessing the [Device APIs](../../200.Server-side-API/?target=_blank#device-apis).                                                                                                                                                                   | The **Device Authentication** service stores the public keys of Mender Clients. |
 | Mender Artifact | Signs and verifies [Mender Artifacts](../../02.Overview/03.Artifact/docs.md). | The **Signing system** stores the private key used for signing Mender artifacts. After an artifact is signed using the private key it is verified by the **Mender Clients**. |
 
 
@@ -175,7 +175,7 @@ The User Administration key can be mounted with the following snippet:
             - ./keys-generated/keys/useradm/private.key:/etc/useradm/rsa/private.pem
 ```
 
-The Management APIs are documented in the [API chapter](../../200.API/?target=_blank#management-apis).
+The Management APIs are documented in the [API chapter](../../200.Server-side-API/?target=_blank#management-apis).
 
 #### Device Authentication
 
@@ -192,7 +192,7 @@ The Device Authentication key can be mounted with the following snippet:
             - ./keys-generated/keys/deviceauth/private.key:/etc/deviceauth/rsa/private.pem
 ```
 
-The Device APIs are documented in the [API chapter](../../200.API/?target=_blank#device-apis).
+The Device APIs are documented in the [API chapter](../../200.Server-side-API/?target=_blank#device-apis).
 
 
 #### Mender Client

diff --git a/07.Server-installation/07.Upgrading/docs.md b/07.Server-installation/07.Upgrading/docs.md
@@ -50,7 +50,7 @@ introduces example tools provided in Mender integration repository.
 Before upgrading it is advisable to clean up any leftover devices from the deviceauth database.
 These can sometimes happen due to device decommissioning.
 You can find instructions on how to clean up the deviceauth database
-in the [Troubleshoot](../../201.Troubleshoot/04.Mender-Server/docs.md) chapter.
+in the [Troubleshoot](../../301.Troubleshoot/04.Mender-Server/docs.md) chapter.
 
 ## Updating your local repository