Docs: Document HTTP and GQL usage for EdgeDB Cloud users (#6893)

* Add HTTP/GQL instructions for EdgeDB Cloud

* Move TOC

This TOC does not appear anywhere if the TOC is at the bottom of the
document, meaning this documentation is hidden from users

* Add HTTP/GQL to Cloud guide

* Remove dash from RST filename

* Update docs/guides/cloud/http_gql.rst

Co-authored-by: Scott Trinh <scott@edgedb.com>

---------

Co-authored-by: Scott Trinh <scott@edgedb.com>

docs/clients/graphql/index.rst

@@ -73,6 +73,12 @@ To execute a GraphQL query against the database ``edgedb`` on the instance
 named ``inst2``, we would send an HTTP request to
 ``http://localhost:10702/db/edgedb/graphql``.
 
+To determine the URL of an EdgeDB Cloud instance, find the host by running
+``edgedb instance credentials -I <org-name>/<instance-name>``. Use the
+``host`` and ``port`` from that table in the URL format at the top of this
+section. Change the protocol to ``https`` since EdgeDB Cloud instances are
+secured with TLS.
+
 .. note::
 
   The endpoint also provides a `GraphiQL`_ interface to explore the GraphQL

docs/clients/http/index.rst

@@ -4,6 +4,13 @@
 EdgeQL over HTTP
 ================
 
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    protocol
+    health-checks
+
 EdgeDB can expose an HTTP endpoint for EdgeQL queries. Since HTTP is a
 stateless protocol, no :ref:`DDL <ref_eql_ddl>`,
 :ref:`transaction commands <ref_eql_statements_start_tx>`,
@@ -37,10 +44,17 @@ Your instance can now receive EdgeQL queries over HTTP at
       called ``edgedb`` is created; all queries are executed against this
       database unless otherwise specified.
 
-    To determine the URL of a remote instance you have linked with the CLI, you
-    can get both the hostname and port of the instance from the "Port" column
-    of the ``edgedb instance list`` table (formatted as ``<hostname>:<port>``).
-    The same guidance on local database names applies here.
+    To determine the URL of an EdgeDB Cloud instance, find the host by running
+    ``edgedb instance credentials -I <org-name>/<instance-name>``. Use the
+    ``host`` and ``port`` from that table in the URL format above this note.
+    Change the protocol to ``https`` since EdgeDB Cloud instances are secured
+    with TLS.
+
+    To determine the URL of a self-hosted remote instance you have linked with
+    the CLI, you can get both the hostname and port of the instance from the
+    "Port" column of the ``edgedb instance list`` table (formatted as
+    ``<hostname>:<port>``). The same guidance on local database names applies
+    here.
 
 
 .. _ref_http_auth:
@@ -56,7 +70,7 @@ By default, the HTTP endpoint uses :eql:type:`cfg::Password` based
 authentication, in which
 `HTTP Basic Authentication
 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme>`_
-is used to provide an edgedb username and password.
+is used to provide an EdgeDB username and password.
 
 .. lint-on
 
@@ -82,10 +96,17 @@ behavior::
     ... };
     OK: CONFIGURE INSTANCE
 
+To authenticate to your EdgeDB Cloud instance, first create a secret key using
+the EdgeDB Cloud UI or :ref:`ref_cli_edgedb_cloud_secretkey_create`. Use the
+secret key as your token with the bearer authentication method. Here is an
+example showing how you might send the query ``select Person {*};`` using cURL:
 
-.. toctree::
-    :maxdepth: 2
-    :hidden:
+.. lint-off
 
-    protocol
-    health-checks
+.. code-block:: bash
+
+    $ curl -G https://<cloud-instance-host>:<cloud-instance-port>/db/edgedb/edgeql \
+       -H "Authorization: Bearer <secret-key> \
+       --data-urlencode "query=select Person {*};"
+
+.. lint-on

docs/guides/cloud/http_gql.rst

@@ -0,0 +1,92 @@
+.. _ref_guide_cloud_http_gql:
+
+===================
+HTTP & GraphQL APIs
+===================
+
+:edb-alt-title: Querying EdgeDB Cloud over HTTP and GraphQL
+
+Using EdgeDB Cloud via HTTP and GraphQL works the same as :ref:`using any other
+EdgeDB instance <ref_edgeql_http>`. The two differences are in **how to
+discover your instance's URL** and **authentication**.
+
+
+Enabling
+========
+
+EdgeDB Cloud can expose an HTTP endpoint for EdgeQL queries. Since HTTP is a
+stateless protocol, no :ref:`DDL <ref_eql_ddl>` or :ref:`transaction commands
+<ref_eql_statements_start_tx>`, can be executed using this endpoint.  Only one
+query per request can be executed.
+
+In order to set up HTTP access to the database add the following to
+the schema:
+
+.. code-block:: sdl
+
+    using extension edgeql_http;
+
+Then create a new migration and apply it using
+:ref:`ref_cli_edgedb_migration_create` and
+:ref:`ref_cli_edgedb_migrate`, respectively.
+
+Your instance can now receive EdgeQL queries over HTTP at
+``https://<host>:<port>/db/<database-name>/edgeql``.
+
+
+Instance URL
+============
+
+To determine the URL of an EdgeDB Cloud instance, find the host by running
+``edgedb instance credentials -I <org-name>/<instance-name>``. Use the
+``host`` and ``port`` from that table in the URL format above this note.
+Change the protocol to ``https`` since EdgeDB Cloud instances are secured
+with TLS.
+
+Your instance can now receive EdgeQL queries over HTTP at
+``https://<hostname>:<port>/db/<database-name>/edgeql``.
+
+
+Authentication
+==============
+
+
+To authenticate to your EdgeDB Cloud instance, first create a secret key using
+the EdgeDB Cloud UI or :ref:`ref_cli_edgedb_cloud_secretkey_create`. Use the
+secret key as your token with the bearer authentication method. Here is an
+example showing how you might send the query ``select Person {*};`` using cURL:
+
+.. lint-off
+
+.. code-block:: bash
+
+    $ curl -G https://<cloud-instance-host>:<cloud-instance-port>/db/edgedb/edgeql \
+       -H "Authorization: Bearer <secret-key> \
+       --data-urlencode "query=select Person {*};"
+
+.. lint-on
+
+
+Usage
+=====
+
+Usage of the HTTP and GraphQL APIs is identical on an EdgeDB Cloud instance.
+Reference the HTTP and GraphQL documentation for more information.
+
+
+HTTP
+----
+
+- :ref:`Overview <ref_edgeql_http>`
+- :ref:`ref_edgeqlql_protocol`
+- :ref:`ref_edgeql_http_health_checks`
+
+
+GraphQL
+-------
+
+- :ref:`Overview <ref_graphql_index>`
+- :ref:`ref_graphql_overview`
+- :ref:`ref_graphql_mutations`
+- :ref:`ref_graphql_introspection`
+- :ref:`ref_cheatsheet_graphql`

docs/guides/cloud/index.rst

@@ -19,6 +19,7 @@ interface nearly identical to the :ref:`EdgeDB UI <ref_cli_edgedb_ui>`.
 
     cli
     web
+    http_gql
     deploy/index
     deploy/vercel
     deploy/netlify