docs: add API overview and describe where to find the APIs (#3362)

docs/astro.config.mjs

@@ -39,6 +39,7 @@ export default defineConfig({
                         { label: 'Current state and roadmap', link: '/introduction/current-state-and-roadmap/' },
                         { label: 'Glossary', link: '/introduction/glossary/' },
                         { label: 'System overview', link: '/introduction/system-overview/' },
+                        { label: 'API overview', link: '/introduction/api-overview/' },
                     ],
                 },
                 {

docs/src/content/docs/for-users/approve-submissions.md

@@ -40,7 +40,7 @@ If you leave any sequences unreleased, you can view, edit, and release (if they
 
 The following API requests all require an authentication token. Please read [Authenticating via API guide](../authenticate-via-api/) for the instructions to obtain the token an include the token in the HTTP header `Authorization: Bearer <authentication token>`.
 
-You also need to identify the URL to the backend of the Loculus instance. Usually, it is at `https://backend.<URL of the Loculus website>`. You can find the exact link in the instance-specific Backend API Documentation which you can find by going to the "API docs" linked in the footer.
+To identify the URL to the backend of the Loculus instance, see [Where are the APIs?](../../introduction/api-overview/#where-are-the-apis).
 
 You can retrieve a list of uploaded but not released sequences by sending a GET request to the endpoint:
 

docs/src/content/docs/for-users/authenticate-via-api.md

@@ -4,10 +4,10 @@ title: Authenticate via API
 
 Some Loculus endpoints require authentication in order to use them. In order to use these endpoints you need to get a JSON web token.
 
-First, you need determine the URL to the [Keycloak](../../introduction/glossary/#keycloak) server and you can find it if you go to the Sign In page or [edit your account](../edit-account/). Given the URL, you can get the token with the following cURL call:
+To determine the URL to the [Keycloak](../../introduction/glossary/#keycloak) server, see [Where are the APIs?](../../introduction/api-overview/#where-are-the-apis). Given the URL, you can get the token with the following cURL call:
 
 ```bash
-KEYCLOAK_TOKEN_URL="https://<Your_Keycloak_URL>/realms/loculus/protocol/openid-connect/token"
+KEYCLOAK_TOKEN_URL="<Your_Keycloak_URL>/realms/loculus/protocol/openid-connect/token"
 USERNAME_LOCULUS="YOUR_USERNAME"
 PASSWORD_LOCULUS="YOUR_PASSWORD"
 

docs/src/content/docs/for-users/submit-sequences.md

@@ -35,7 +35,7 @@ It is possible to upload sequences through an HTTP API. We also plan to release
 
 To upload sequences through the HTTP API you will need to:
 
-1. Identify the URL to the backend of the Loculus instance. Usually, it is at `https://backend.<URL of the Loculus website>`. You can find the exact link in the instance-specific Backend API Documentation which you can find by going to the "API docs" linked in the footer.
+1. To identify the URL to the backend of the Loculus instance, see [Where are the APIs?](../../introduction/api-overview/#where-are-the-apis).
 2. Retrieve an authentication JSON web token: see the [Authenticating via API guide](../authenticate-via-api/).
 3. Identify the Group ID of your group: you can find it on the page of your group.
 4. Send a POST request:

docs/src/content/docs/introduction/api-overview.md

@@ -0,0 +1,17 @@
+---
+title: API overview
+---
+
+Loculus has been designed with an API-first approach: everything that you can do on the website, you can also access through an API.
+
+As shown in the [system overview](../system-overview/), Loculus consists of several sub-services which have their own APIs. Please note that the API interface has not been finalized yet and may change rapidly until Loculus 1.0 is officially released (see [current state and roadmap](../current-state-and-roadmap/)). In particular, we have plans to unify the APIs more (see [GitHub ticket](https://github.com/loculus-project/loculus/issues/855)).
+
+## Where are the APIs?
+
+You can find the exact API host URLs on the "API Documentation" page of the instance that you are using. There is a link to the page in the footer of the website, you can also find it under `<URL of the website>/api-documentation`.
+
+## Which APIs should you use?
+
+- **Backend:** The backend service is the central service. It should be used for data submission and submitting group management and is also the API that the preprocessing pipeline talks to.
+- **LAPIS:** The [LAPIS service](https://github.com/GenSpectrum/LAPIS) contains the released data and should be used to query and download data.
+- **Keycloak:** The [Keycloak](https://www.keycloak.org/) service is used for authentication and should be used to obtain authentication tokens and user profile management.