rename GraphQL API to Internal GraphQL API

Author: hughns

docs/README.md

@@ -14,7 +14,7 @@ This documentation has four main sections:
 
 - The [installation guide](./setup/README.md) will guide you through the process of setting up the `matrix-authentication-service` on your own infrastructure.
 - The topics sections goes into more details about how the service works, like the [policy engine](./topics/policy.md) and how [authorization sessions](./topics/authorization.md) are managed.
-- The reference documentation covers [configuration options](./reference/configuration.md), the [GraphQL API](./reference/graphql.md), the [scopes](./reference/scopes.md) supported by the service, and the [command line interface](./reference/cli/).
+- The reference documentation covers [configuration options](./reference/configuration.md), the [Admin API](./api/index.html), the [scopes](./reference/scopes.md) supported by the service, and the [command line interface](./reference/cli/).
 - The developer documentation is intended for people who want to [contribute to the project](./development/contributing.md). Developers may also be interested in:
   - Technical documentation for individual crates: [`rustdoc`](./rustdoc/mas_handlers/)
   - UI components: [`storybook`](./storybook/)

docs/SUMMARY.md

@@ -26,7 +26,6 @@
 # Reference
 
 - [Configuration file reference](./reference/configuration.md)
-- [GraphQL API](./reference/graphql.md)
 - [Admin API](./api/index.html)
 - [OAuth 2.0 scopes](./reference/scopes.md)
 - [Command line tool](./reference/cli/README.md)
@@ -42,6 +41,7 @@
 - [Contributing](./development/contributing.md)
 - [Architecture](./development/architecture.md)
 - [Database](./development/database.md)
+- [Internal GraphQL API](./development/graphql.md)
 
 ---
 

docs/reference/graphql.md renamed to docs/development/graphql.md

@@ -1,11 +1,10 @@
-# GraphQL API
+# Internal GraphQL API
 
-MAS provides a GraphQL API which serves two purposes:
+> **Note:** This API used to be the way for external tools to interact with MAS. However, **external usage is now deprecated** in favour of the REST based [Admin API](../topics/admin-api.md). External access to this API will be removed in a future release.
 
- - it is used by the self-service user interface (usually accessible on `/account/`), for users to manage their own account.
- - it can be used with external tools to manage the service.
+MAS uses an internal GraphQL API which is used by the self-service user interface (usually accessible on `/account/`), for users to manage their own account.
 
-The endpoint for this API can be discovered through the OpenID Connect discovery document, under the `"org.matrix.matrix-authentication-service.graphql_endpoint` key.
+The endpoint for this API can be discovered through the OpenID Connect discovery document, under the `org.matrix.matrix-authentication-service.graphql_endpoint` key.
 Though it is usually hosted at `https://<mas-host>/graphql`.
 
 GraphQL uses [a self-describing schema](https://github.com/matrix-org/matrix-authentication-service/blob/main/frontend/schema.graphql), which means that the API can be explored in tools like the GraphQL Playground.
@@ -23,5 +22,5 @@ With only this scope, the session will be authorized as the user who owns the ac
 
 To get full access to the GraphQL API, the access token must have the [`urn:mas:admin`] scope in addition to the [`urn:mas:graphql:*`] scope.
 
-[`urn:mas:graphql:*`]: ./scopes.md#urnmasgraphql
-[`urn:mas:admin`]: ./scopes.md#urnmasadmin
+[`urn:mas:graphql:*`]: ../reference/scopes.md#urnmasgraphql
+[`urn:mas:admin`]: ../reference/scopes.md#urnmasadmin

docs/topics/admin-api.md

@@ -3,6 +3,8 @@
 MAS provides a REST-like API for administrators to manage the service.
 This API is intended to build tools on top of MAS, and is only available to administrators.
 
+> **Note:** This Admin API is now the correct way for external tools to interact with MAS. External access to the [Internal GraphQL API](../development/graphql.md) is deprecated and will be removed in a future release.
+
 ## Enabling the API
 
 The API isn't exposed by default, and must be added to either a public or a private HTTP listener.
@@ -37,7 +39,7 @@ http:
 ## Reference documentation
 
 The API is documented using the [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0).
-The API schema is avaialble [here](../api/spec.json).
+The API schema is available [here](../api/spec.json).
 This schema can be viewed in tools like Swagger UI, available [here](../api/).
 
 If admin API is enabled, MAS will also serve the specification at `/api/spec.json`, with a Swagger UI available at `/api/doc/`.
@@ -157,7 +159,7 @@ When querying a list of resources, the response is generally shaped like this:
 }
 ```
 
-The `meta` will have the total numer of items in it, and the `links` object contains the links to the next and previous pages, if any.
+The `meta` will have the total number of items in it, and the `links` object contains the links to the next and previous pages, if any.
 
 Pagination is cursor-based, where the ID of items is used as the cursor.
 Resources can be paginated forwards using the `page[after]` and `page[first]` parameters, and backwards using the `page[before]` and `page[last]` parameters.

docs/topics/authorization.md

@@ -86,11 +86,11 @@ the API can be requested by a session which has the [`urn:mas:graphql:*`] and th
 MAS supports a few different authorization grants for OAuth 2.0 sessions.
 Whilst this section won't go into the technical details of how those grants work, it's important to understand what they are and what they are used for.
 
-| Grant type                                          | Entity | User interaction | Matrix C-S API | Synapse admin API |  MAS GraphQL API |
-| --------------------------------------------------- | ------ | ---------------- | -------------- | ----------------- | ---------------- |
-| [Authorization code](#authorization-code-grant)     | User   | Same device      | Yes            | Yes               | Yes              |
-| [Device authorization](#device-authorization-grant) | User   | Other device     | Yes            | Yes               | Yes              |
-| [Client credentials](#client-credentials-grant)     | Client | None             | No             | No[^admin]        | No               |
+| Grant type                                          | Entity | User interaction | Matrix C-S API | Synapse admin API |  MAS Internal GraphQL API | MAS Admin API |
+| --------------------------------------------------- | ------ | ---------------- | -------------- | ----------------- | ------------------------- | ------------- |
+| [Authorization code](#authorization-code-grant)     | User   | Same device      | Yes            | Yes               | Yes                       | TODO: ?       |
+| [Device authorization](#device-authorization-grant) | User   | Other device     | Yes            | Yes               | Yes                       | TODO: ?       |
+| [Client credentials](#client-credentials-grant)     | Client | None             | No             | No[^admin]        | No                        | TODO: ?       |
 
 [^admin]: The Synapse admin API doesn't strictly require a user, but Synapse doesn't support client-only sessions yet. In the future, it will be possible to leverage the client credentials grant to access the Synapse admin API.