From f00c6ee47afd842e791dc7c2c5f89fb3da44073d Mon Sep 17 00:00:00 2001 From: Hampus Date: Sun, 6 Sep 2026 23:50:52 +0200 Subject: [PATCH] docs(http-api): name the endpoint a third-party client reads (#2564) --- fluxer_docs/src/content/docs/http-api/index.md | 2 +- fluxer_docs/src/content/docs/http-api/instance.mdx | 2 +- fluxer_docs/src/content/docs/index.md | 4 +++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/fluxer_docs/src/content/docs/http-api/index.md b/fluxer_docs/src/content/docs/http-api/index.md index 14224bb38..210ac592f 100644 --- a/fluxer_docs/src/content/docs/http-api/index.md +++ b/fluxer_docs/src/content/docs/http-api/index.md @@ -4,7 +4,7 @@ title: HTTP API description: Request format, body representations, shared headers, cross-origin policy, and the error objects. --- -The Fluxer HTTP API is the set of routes a client calls to read and change data. Every route is published under `/v1`, and `/v1` is the only version. The base URL comes from `endpoints.api` in the [instance discovery document](/http-api/instance/#get-instance-discovery), which is served unversioned at `/.well-known/fluxer`. +The Fluxer HTTP API is the set of routes a client calls to read and change data. Every route is published under `/v1`, and `/v1` is the only version. The base URL comes from the [instance discovery document](/http-api/instance/#get-instance-discovery), which is served unversioned at `/.well-known/fluxer`. A third-party client reads `endpoints.api_public` there, and the first-party web application reads `endpoints.api_client`. Every route is also mounted at the root, so a path resolves with or without the prefix. A client MUST use the `/v1` form. [Download stored object](/http-api/downloads/#download-stored-object) is the one exception, and it resolves at the root alone. diff --git a/fluxer_docs/src/content/docs/http-api/instance.mdx b/fluxer_docs/src/content/docs/http-api/instance.mdx index 197e3d662..f958985c1 100644 --- a/fluxer_docs/src/content/docs/http-api/instance.mdx +++ b/fluxer_docs/src/content/docs/http-api/instance.mdx @@ -57,7 +57,7 @@ Each value is an absolute URL supplied by the operator. A value can be a bare or | gift | string | Gift link base URL | | webapp | string | Web application base URL | -1 Both fields are the same configured client API endpoint, while `api_public` is the separately configured public API endpoint +1 Both fields are the same configured client API endpoint, which the first-party web application reads. `api_public` is the separately configured public API endpoint, which a bot, a library, or any other third-party client reads. A deployment can point the two at one origin, and the instance Fluxer hosts does not 2 The value is the configured Gateway endpoint and its scheme is `ws` or `wss` as the operator configured it diff --git a/fluxer_docs/src/content/docs/index.md b/fluxer_docs/src/content/docs/index.md index f3307d7f9..f086b1617 100644 --- a/fluxer_docs/src/content/docs/index.md +++ b/fluxer_docs/src/content/docs/index.md @@ -43,9 +43,11 @@ A client that knows only a Fluxer origin reads endpoint discovery first. `GET /. GET https://example.com/.well-known/fluxer ``` +The instance Fluxer hosts answers discovery at `https://fluxer.app/.well-known/fluxer`. That origin is the one thing a client is given. Every base URL below it still comes from the response. + It returns the [instance discovery object](/http-api/instance/#instance-discovery-object). Every base URL a client uses comes from the [instance endpoints object](/http-api/instance/#instance-endpoints-object) inside it. A client MUST read every base URL from that response, and it MUST NOT derive one from the origin it was given or assume an official Fluxer domain. -Take `endpoints.api` from that response, then send a credential in the `Authorization` header. +Take the base URL for the kind of client being built, then send a credential in the `Authorization` header. A bot, a library, or any other third-party client takes `endpoints.api_public`. `endpoints.api_client` is the endpoint the first-party web application uses, and `endpoints.api` repeats it. ```text GET https://api.example.com/v1/users/@me