DOC-4676 Restructure API reference pages

modules/ROOT/nav.adoc

@@ -3,25 +3,23 @@
 * xref:getting-started:real-time-data-pipelines-tutorial.adoc[]
 
 .Development
-* Produce and consume messages
-** xref:developing:produce-consume-astra-portal.adoc[]
-** xref:developing:produce-consume-pulsar-client.adoc[]
-** Client applications
-*** xref:developing:clients/index.adoc[]
-*** xref:developing:clients/java-produce-consume.adoc[]
-*** xref:developing:clients/python-produce-consume.adoc[]
-*** xref:developing:clients/csharp-produce-consume.adoc[]
-*** xref:developing:clients/golang-produce-consume.adoc[]
-*** xref:developing:clients/nodejs-produce-consume.adoc[]
-*** xref:developing:clients/spring-produce-consume.adoc[]
-** {pulsar-short} subscriptions
-*** xref:ROOT:astream-subscriptions.adoc[]
-*** xref:ROOT:astream-subscriptions-exclusive.adoc[]
-*** xref:ROOT:astream-subscriptions-shared.adoc[]
-*** xref:ROOT:astream-subscriptions-failover.adoc[]
-*** xref:ROOT:astream-subscriptions-keyshared.adoc[]
+* xref:developing:produce-consume-astra-portal.adoc[]
+* xref:developing:produce-consume-pulsar-client.adoc[]
+* Client applications
+** xref:developing:clients/index.adoc[]
+** xref:developing:clients/java-produce-consume.adoc[]
+** xref:developing:clients/python-produce-consume.adoc[]
+** xref:developing:clients/csharp-produce-consume.adoc[]
+** xref:developing:clients/golang-produce-consume.adoc[]
+** xref:developing:clients/nodejs-produce-consume.adoc[]
+** xref:developing:clients/spring-produce-consume.adoc[]
+* {pulsar-short} subscriptions
+** xref:ROOT:astream-subscriptions.adoc[]
+** xref:ROOT:astream-subscriptions-exclusive.adoc[]
+** xref:ROOT:astream-subscriptions-shared.adoc[]
+** xref:ROOT:astream-subscriptions-failover.adoc[]
+** xref:ROOT:astream-subscriptions-keyshared.adoc[]
 * xref:developing:astream-functions.adoc[]
-* xref:developing:configure-pulsar-env.adoc[]
 * xref:developing:starlight.adoc[]
 * xref:developing:astream-cdc.adoc[]
 * xref:developing:gpt-schema-translator.adoc[]
@@ -50,10 +48,11 @@
 * xref:operations:astream-pricing.adoc[]
 * xref:operations:monitoring/stream-audit-logs.adoc[]
 
-.API references
+.API and CLI references
 * xref:apis:index.adoc[]
-* xref:developing:using-curl.adoc[]
 * xref:apis:api-operations.adoc[]
+* xref:developing:using-curl.adoc[]
+* xref:developing:configure-pulsar-env.adoc[]
 * xref:developing:astra-cli.adoc[]
 
 .Frequently asked questions

modules/ROOT/pages/astream-faq.adoc

@@ -77,9 +77,9 @@ However, shared clusters don't support private links.
 
 For more information, see xref:operations:astream-pricing.adoc[].
 
-=== What are the differences in geo-replication for shared clusters and Streaming Capacity Units?
+=== What are the differences in georeplication for shared clusters and Streaming Capacity Units?
 
-Geo-replication is available for both shared clusters and Streaming Capacity Units.
+Georeplication is available for both shared clusters and Streaming Capacity Units.
 Both cluster types can replicate to other clusters, but there are some differences:
 
 Connections::
@@ -92,7 +92,7 @@ Shared clusters can replicate between any xref:operations:astream-regions.adoc[s
 +
 Streaming Capacity Units can use almost any region supported by your cloud provider, as well as across cloud providers.
 
-For more on geo-replication, see xref:operations:astream-georeplication.adoc[].
+For more on georeplication, see xref:operations:astream-georeplication.adoc[].
 
 == Security and access control
 
@@ -117,7 +117,11 @@ The following questions are related to application development with {product}.
 
 === What APIs are available?
 
-See xref:apis:index.adoc[].
+See the following:
+
+* xref:apis:index.adoc[]
+* xref:apis:api-operations.adoc[]
+* xref:developing:using-curl.adoc[]
 
 === Can I migrate data from my existing {pulsar-short} cluster to {product}?
 

modules/ROOT/pages/index.adoc

@@ -30,13 +30,9 @@
         svg:ROOT:what-is-astra-db.svg[role="mx-auto my-auto w-8 h-8"]
     </div>
 
-    <h3 class="discrete !text-h2 !m-0 [&>a]:text-white">Streaming Guides</h3>
+    <h3 class="discrete !text-h2 !m-0 [&>a]:text-white">APIs and integrations</h3>
 
-    Learn about the amazing things you can do with all of our streaming products.
-    We've included best practices for Apache Pulsar, a full connector reference,
-    and examples for getting the most out of Astra's CDC feature.
-
-    xref:streaming-learning:ROOT:index.adoc[Get started with streaming examples and guides]
+    <p>{product} goes beyond the {astra-ui}. You can use xref:apis:index.adoc[{product} APIs], xref:developing:clients/index.adoc[{pulsar} clients], and related tools to manage your streaming tenants and resources, develop applications, and xref:streaming-learning:pulsar-io:connectors/index.adoc[integrate] with popular sinks and sources.</p>
 
   </div>
 
@@ -52,8 +48,7 @@
 
     <div><h3 class="discrete !text-h2 !m-0 [&>a]:text-white">Real Time Processing</h3></div>
 
-    Legacy batch processing jobs result in stale data that
-    can slow down an entire business.
+    Legacy batch processing jobs result in stale data that can slow down an entire business.
     With {product}, customers can capture event data and data changes in real-time,
     process that data and take action to create a more responsive, nimble organization.
 
@@ -67,10 +62,9 @@
 
     <div><h3 class="discrete !text-h2 !m-0 [&>a]:text-white">Event Driven Architecture</h3></div>
 
-    {product} provides a unified
-    messaging platform that addresses streaming, pub/sub and queuing use cases with
-    low latency and at massive scale. Organizations that are struggling to make
-    their legacy messaging technologies keep up will find {product} to be a
+    {product} provides a unified messaging platform that addresses streaming,
+    pub/sub and queuing use cases with low latency and at massive scale.
+    Organizations that need to maintain legacy messaging technologies will find {product} to be a
     frictionless path to modernization.
 
   </div>
@@ -83,7 +77,7 @@
 
     <div><h3 class="discrete !text-h2 !m-0 [&>a]:text-white">Change Data Capture</h3></div>
 
-    Change Data Capture (CDC) enables you to send data changes in real time throughout your entire ecosystem.
+    xref:developing:astream-cdc.adoc[Change Data Capture (CDC)] enables you to send data changes in real time throughout your entire ecosystem.
     With a wide range of connectors to data warehouses, messaging systems, data lakes as well as client libraries, you can send your data wherever it needs to go in real time.
 
   </div>

modules/ROOT/partials/curl-file-input-tip.adoc

@@ -0,0 +1,8 @@
+[TIP]
+====
+To use a file as input for a curl command, use the `@` symbol followed by the file path and name.
+
+Relative paths are resolved from the current working directory.
+
+The file must be in a location that the shell can access, and the user running the command must have permission to read the file.
+====

modules/ROOT/partials/curl-get-template-tip.adoc

@@ -0,0 +1,4 @@
+[TIP]
+====
+Use the response from the `GET` request as a template for the `POST` request body.
+====

modules/ROOT/partials/format-api-response.adoc

@@ -0,0 +1,9 @@
+The default response is a single JSON string.
+
+You can use modifications like `| jq .` or `| python3 -mjson.tool` to format the output for easier reading.
+Formatting the response is optional; it isn't required to execute API requests.
+
+Many examples in this reference use `| python3 -mjson.tool` to format the JSON response.
+Additionally, the examples use the `-sS --fail` options to suppress trivial output and handle errors more gracefully while passing the content of successful responses to `stdout`.
+
+Omit the `-sS --fail` options for debugging or to get the full output, including progress bars and warnings.

modules/ROOT/partials/get-web-service-url.adoc

@@ -0,0 +1,17 @@
+To get the Web Service URL, do the following:
++
+. In the {astra-ui-link} header, click icon:grip[name="Applications"], and then select *Streaming*.
+. Click the name of your tenant.
+. Click the *Connect* tab.
+. Find the *Tenant Details* section.
+This section includes the essential information you need to communicate with your {pulsar-short} tenant, including the *Web Service URL*.
++
+image::developing:tenant-details.png[Tenant details in {product}]
++
+[TIP]
+====
+The *Web Service URL* _isn't_ the same as the {pulsar-short} *Broker Service URL*.
+
+Web Service URLs start with `http`.
+Broker Service URLs start with `pulsar(+ssl)`.
+====

modules/ROOT/partials/subscription-prereq.adoc

@@ -13,11 +13,11 @@ This example requires the following:
 * In the `pulsar-subscription-example` repo, navigate to `src/main/resources`, and then edit `application.properties` to connect to your {product} cluster:
 +
 .application.properties
-[source,plain,subs="+quotes"]
+[source,conf,subs="+quotes"]
 ----
 service_url=**BROKER_SERVICE_URL**
 namespace=default
 tenant_name=my-tenant
-authentication_token=**ASTRA_DB_APPLICATION_TOKEN**
+authentication_token=**ASTRA_APPLICATION_TOKEN**
 topic_name=my-topic
 ----