From f6c3b9d2e6d49f976603a93c5cbb3e86119b87bb Mon Sep 17 00:00:00 2001
From: Simon Fels <simon.fels@canonical.com>
Date: Tue, 10 Sep 2024 06:23:08 +0200
Subject: [PATCH] fix(ref): rework description on the API landing page

---
 reference/api-reference.md | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/reference/api-reference.md b/reference/api-reference.md
index 341d00f1..30060a42 100644
--- a/reference/api-reference.md
+++ b/reference/api-reference.md
@@ -1,18 +1,29 @@
 (ref-api)=
 # API reference
 
-All communication between AMS and its clients happen using a RESTful API over HTTP. This API is encapsulated over either TLS (for remote operations) or a Unix socket (for local operations).
+Anbox Cloud includes various APIs to help you build solutions with it. This page provides an overview of the available APIs and their uses.
 
-## APIs and their structure
+All these APIs except for the {ref}`anbox-https-api` have an auto-generated Open API specification describing its API endpoints.
 
-Anbox Cloud provides the following APIs:
+## Available APIs
 
-* AMS HTTP API
-* Anbox Cloud HTTP API
-* Stream Gateway API
-* Anbox Platform SDK API
+### AMS HTTP API
 
-All these APIs except for the {ref}`anbox-https-api` have an auto-generated specification describing its API endpoints.
+The AMS services provide an HTTP based API to help you manage all of its objects. Internally the `amc` client uses the same API to perform its operation.
+
+You can find the OpenAPI specification [here](https://canonical.github.io/anbox-cloud.github.com/latest/ams/).
+
+### Anbox HTTP API
+
+The Anbox runtime inside each instance managed by the AMS provides an HTTP API over a UNIX domain socket that helps interacting with various functionalities offered by Anbox. This includes the injection of position or sensor events into Android, among other things.
+
+You can find the API specifiction at {ref}`anbox-https-api`.
+
+### Anbox Stream Gateway API
+
+The Anbox Stream Gateway service provides an API endpoint to help you to manage streaming sessions.
+
+You can find the OpenAPI specification [here](https://canonical.github.io/anbox-cloud.github.com/latest/anbox-stream-gateway).
 
 ```{toctree}
 :hidden: