From e82d6b1ea455952a20017cf301de40dea629b06e Mon Sep 17 00:00:00 2001
From: Fabian Affolter <mail@fabian-affolter.ch>
Date: Tue, 14 Apr 2020 10:27:10 +0200
Subject: [PATCH] Minor re-work (#1661)

* Minor re-work

* Fix typo
---
 API.md | 67 +++++++++++++++++++++++-----------------------------------
 1 file changed, 27 insertions(+), 40 deletions(-)

diff --git a/API.md b/API.md
index 2a827d6ab..79705678b 100644
--- a/API.md
+++ b/API.md
@@ -2,7 +2,8 @@
 
 ## Supervisor RESTful API
 
-Interface for Home Assistant to control things from supervisor.
+The RESTful API for Home Assistant allows you to control things around
+around the Supervisor and other components.
 
 On error / Code 400:
 
@@ -22,8 +23,10 @@ On success / Code 200:
 }
 ```
 
-For access to API you need use a authorization header with a `Bearer` token.
-They are available for Add-ons and the Home Assistant using the `SUPERVISOR_TOKEN` environment variable.
+To access the API you need use an authorization header with a `Bearer` token.
+
+The token is available for add-ons and Home Assistant using the 
+`SUPERVISOR_TOKEN` environment variable.
 
 ### Supervisor
 
@@ -33,7 +36,7 @@ This API call don't need a token.
 
 - GET `/supervisor/info`
 
-The addons from `addons` are only installed one.
+Shows the installed add-ons from `addons`.
 
 ```json
 {
@@ -90,11 +93,11 @@ Optional:
 
 - POST `/supervisor/reload`
 
-Reload addons/version.
+Reload the add-ons/version.
 
 - GET `/supervisor/logs`
 
-Output is the raw docker log.
+Output is the raw Docker log.
 
 - GET `/supervisor/stats`
 
@@ -113,7 +116,7 @@ Output is the raw docker log.
 
 - GET `/supervisor/repair`
 
-Repair overlayfs issue and restore lost images
+Repair overlayfs issue and restore lost images.
 
 ### Snapshot
 
@@ -134,7 +137,6 @@ Repair overlayfs issue and restore lost images
 ```
 
 - POST `/snapshots/reload`
-
 - POST `/snapshots/new/upload`
 
 return:
@@ -208,9 +210,7 @@ return:
 ```
 
 - POST `/snapshots/{slug}/remove`
-
 - GET `/snapshots/{slug}/download`
-
 - POST `/snapshots/{slug}/restore/full`
 
 ```json
@@ -233,11 +233,8 @@ return:
 ### Host
 
 - POST `/host/reload`
-
 - POST `/host/shutdown`
-
 - POST `/host/reboot`
-
 - GET `/host/info`
 
 ```json
@@ -254,7 +251,7 @@ return:
 
 - GET `/host/logs`
 
-Return host dmesg
+Return the host log messages (dmesg).
 
 - POST `/host/options`
 
@@ -311,7 +308,7 @@ Return host dmesg
 
 - POST `/os/config/sync`
 
-Load host configs from a USB stick.
+Load host configurations from an USB stick.
 
 ### Hardware
 
@@ -354,7 +351,7 @@ Load host configs from a USB stick.
 
 - POST `/hardware/trigger`
 
-Trigger an udev reload
+Trigger an UDEV reload.
 
 ### Home Assistant
 
@@ -414,7 +411,7 @@ Output is the raw Docker log.
 }
 ```
 
-Image with `null` and version_latest with `null` reset this options.
+Image with `null` and `version_latest` with `null` reset this options.
 
 - POST/GET `/core/api`
 
@@ -551,13 +548,9 @@ Get all available add-ons.
 ```
 
 - GET `/addons/{addon}/icon`
-
 - GET `/addons/{addon}/logo`
-
 - GET `/addons/{addon}/changelog`
-
 - GET `/addons/{addon}/documentation`
-
 - POST `/addons/{addon}/options`
 
 ```json
@@ -574,7 +567,7 @@ Get all available add-ons.
 }
 ```
 
-Reset custom network/audio/options, set it `null`.
+Reset custom network, audio and options, set it to `null`.
 
 - POST `/addons/{addon}/security`
 
@@ -587,28 +580,22 @@ This function is not callable by itself.
 ```
 
 - POST `/addons/{addon}/start`
-
 - POST `/addons/{addon}/stop`
-
 - POST `/addons/{addon}/install`
-
 - POST `/addons/{addon}/uninstall`
-
 - POST `/addons/{addon}/update`
-
 - GET `/addons/{addon}/logs`
 
 Output is the raw Docker log.
 
 - POST `/addons/{addon}/restart`
-
 - POST `/addons/{addon}/rebuild`
 
-Only supported for local build addons
+Only supported for local build add-ons.
 
 - POST `/addons/{addon}/stdin`
 
-Write data to add-on stdin
+Write data to add-on stdin.
 
 - GET `/addons/{addon}/stats`
 
@@ -629,7 +616,7 @@ Write data to add-on stdin
 
 - POST `/ingress/session`
 
-Create a new Session for access to ingress service.
+Create a new session for access to the ingress service.
 
 ```json
 {
@@ -656,8 +643,8 @@ Return a list of enabled panels.
 
 - VIEW `/ingress/{token}`
 
-Ingress WebUI for this Add-on. The addon need support HASS Auth!
-Need ingress session as cookie.
+Ingress WebUI for this add-on. The add-on need support for the Home Assistant
+authentication system. Needs an ingress session as cookie.
 
 ### discovery
 
@@ -1113,18 +1100,18 @@ return:
 }
 ```
 
-### Auth / SSO API
+### Authentication/SSO API
 
-You can use the user system on homeassistant. We handle this auth system on
-supervisor.
+You can use the user system from Home Assistant. The auth system can be handled
+with the Supervisor.
 
-You can call post `/auth`
+`/auth` is accepting POST calls.
 
 We support:
 
-- Json `{ "user|name": "...", "password": "..." }`
-- application/x-www-form-urlencoded `user|name=...&password=...`
-- BasicAuth
+- JSON: `{ "user|name": "...", "password": "..." }`
+- `application/x-www-form-urlencoded`: `user|name=...&password=...`
+- Basic Authentication
 
 * POST `/auth/reset`