Merge pull request #190 from quixio/tonybedford/sc-45562/reader-write…

…r-signalr-docs-need-updating

Update Streaming Reader / Writer APIs section of docs

BEST-PRACTICE.md

@@ -56,7 +56,7 @@ The main left-hand navbar, or TOC, provides the main element of the information
 3. **Client Library**. The Quix Streams client library provides a very effective way to write scalable real-time streaming applications. Using Quix Streams you can create solutions that work with Quix Platform, or with other services depending on your requirement. The `Client Library` section also includes API reference documentation generated from source code for both the Python and C# versions of Quix Streams.
 4. **APIs**. These are additional Quix APIs, other than those provided by Quix Streams. The documentation consists of general topics, as well as REST API references based on OAS3 documents.
 
-The longer topics can be navigated using the right-hand "on this page" TOC. This allows you to quickly navigate through the sections of a topic. It is important that topics are structured with the correct heading levels. There should only ever be one `h1` heading per topic, but there can be several `h2`s. Section headings below `h3` should be used sparingly, as they won't be displayed in the navigation, and could indicate the topic has become too convoluted. The solution can be to split the topic into multiple topics, or otherwise rethink the structure.
+The longer topics can be navigated using the right-hand "on this page" TOC. This enables you to quickly navigate through the sections of a topic. It is important that topics are structured with the correct heading levels. There should only ever be one `h1` heading per topic, but there can be several `h2`s. Section headings below `h3` should be used sparingly, as they won't be displayed in the navigation, and could indicate the topic has become too convoluted. The solution can be to split the topic into multiple topics, or otherwise rethink the structure.
 
 It's important that the end of the topic should not leave the reader hanging, so a well-written topic ideally ends with a "Next steps" section, where the reader can find suggested resources that enable their Quix learning journey to continue. 
 
@@ -66,7 +66,7 @@ As mentioned before, tutorials not only serve to inform, but to provide a learni
 
 **IMPORTANT:** Tutorials that fail, because they are not maintained, create the opposite to the required experience - they leave the reader confused, and create an unpleasant (not very fun) experience. They leave the reader feeling disengaged, and reluctant to explore further.
 
-As tutorials tend to be longer-form material, Quix uses the approach of splitting the tutorials up into *parts*. This allows the reader to attempt a part, leave it to one side should they so wish, and then return to continue with the tutorial when time permits. To help the tutorial be manageable, each part is further divided into steps. Steps are numbered to provide an additional source of reference, and make working through the procedure easier to track. 
+As tutorials tend to be longer-form material, Quix uses the approach of splitting the tutorials up into *parts*. This enables the reader to attempt a part, leave it to one side should they so wish, and then return to continue with the tutorial when time permits. To help the tutorial be manageable, each part is further divided into steps. Steps are numbered to provide an additional source of reference, and make working through the procedure easier to track. 
 
 The Quix technical writing team attempts to keep the structure of each tutorial consistent, so that the layout for readers feels familiar. An example of this structure can be found in the [Sentiment Analysis tutorial](https://docs.quix.io/platform/tutorials/sentiment-analysis/index.html). Writers should always try to follow this structure consistently. 
 
@@ -76,7 +76,7 @@ Another approach (and perhaps to be preferred), is to create a new separate tuto
 
 ## "Docs as code" and tooling
 
-Quix documentation uses a "docs as code" approach. What this means is the same tools that are used to manage code are used to manage documentation. There are numerous reasons for this. Primarily, it allows for easier contribution and participation, as tools and technologies, such as Git, GitHub, Markdown, issue trackers, and related workflows are familiar and widely adopted. 
+Quix documentation uses a "docs as code" approach. What this means is the same tools that are used to manage code are used to manage documentation. There are numerous reasons for this. Primarily, it enables easier contribution and participation, as tools and technologies, such as Git, GitHub, Markdown, issue trackers, and related workflows are familiar and widely adopted. 
 
 Quix uses GitHub as the repository for the Markdown files that make up the Quix technical documentation, and contributors can avail themselves of full revision history, clones and forks, PRs, PR reviews, branches, tagging, and so on. 
 

WRITING-STYLE.md

@@ -357,7 +357,7 @@ Make sure you write the correct case for product names:
 
 ## Links
 
-Avoid excessive interlinking (use links sparingly), as readers tend to link hop and soon get disorientated. Consider having a "next steps" section at the end of a topic with cross-references to useful material. This allows readers to progress through the material without distraction, and thenpursue additional information should they require it.
+Avoid excessive interlinking (use links sparingly), as readers tend to link hop and soon get disorientated. Consider having a "next steps" section at the end of a topic with cross-references to useful material. This enables readers to progress through the material without distraction, and thenpursue additional information should they require it.
 
 External links should open in a new tab. This can be achieved by constructing links using `{target=_blank}`, as follows:
 

docs/apis/api-references.md

@@ -0,0 +1,18 @@
+## API reference guides
+
+An OAS3 API reference guides are available for HTTP/REST APIs. These are rendered using [Swagger](https://swagger.io/){target=_blank}. 
+
+The URLs for the API references are specific to your environment, so you can easily test out API calls on your environment using the API reference. You'll need to [get you environment ID](../platform/how-to/get-environment-id.md). The exception to this is the Portal API, which is account-wide.
+
+| API | API reference URL (Swagger documentation)|
+|---|---|
+| Streaming Writer | https://writer-`<environment-id>`.platform.quix.ai/swagger |
+| Streaming Reader | No HTTP/REST interface - SignalR (WebSockets or Long Polling)|
+| Portal | https://portal-api.platform.quix.ai/swagger |
+| Query | https://telemetry-query-`<environment-id>`.platform.quix.ai/swagger |
+
+Replace `<environment-id>` with your [environment ID](../platform/how-to/get-environment-id.md).
+
+!!! tip
+
+    Once you access the API reference, you can select the version of the API you require from the `Select a definition` dropdown list.

docs/apis/http-requests.md

@@ -0,0 +1,85 @@
+# HTTP requests
+
+How you send HTTP requests REST APIs varies depending on the client or language you’re using.
+
+## Sign requests using your PAT
+
+Make sure you accompany each request to the API with an `Authorization` header using your [Personal Access Token (PAT)](../platform/how-to/personal-access-token-pat.md) as a bearer token, as follows:
+
+``` http
+Authorization: bearer <token>
+```
+
+Replace `<token>` with your [Personal Access Token (PAT)](../platform/how-to/personal-access-token-pat.md). 
+
+For example, if you’re using Curl on the command line, you can set the header using the `-H` flag:
+
+``` shell
+curl -H "Authorization: bearer <token>" ...
+```
+
+If you fail to send a valid Authorization header, the API will respond with a `401 UNAUTHORIZED` status code.
+
+## Endpoint URLs
+
+APIs are available on a per-environment basis (with the exception of the Portal API), so the endpoint URL is based on your environment ID. 
+
+Read the documentation on [how to obtain your environment ID](../platform/how-to/get-environment-id.md).
+
+The API endpoint URL has the following format:
+
+```
+https://<api-name>-<environment-id>.platform.quix.ai/<action>
+```
+
+So, for example, the endpoint URL for the streaming writer might resemble the following:
+
+```
+https://writer-acme-weather.platform.quix.ai/<action>
+```
+
+The API is `writer`, and the environment ID is `acme-weather`.
+
+## HTTP method
+
+Endpoints in the API use HTTP methods such as `POST` and `PUT` methods. Ensure your HTTP client sends the correct request method.
+
+Using `curl`, you can specify the request method with the `-X <POST|PUT>` flag, for example:
+
+```bash
+curl -X PUT ...
+```
+
+## Payload
+
+For most methods, you’ll need to send a JSON object containing supported parameters. You’ll also need to set the appropriate content type for the payload you’re sending:
+
+```bash
+curl -H "Content-Type: application/json" ...
+```
+
+!!! warning
+
+	You **must** specify the content type of your payload. Failing to include this header will result in a `415 UNSUPPORTED MEDIA TYPE` status code.
+
+You can send data using the `curl` flag `-d`. This should be followed by either a string of JSON data, or a string starting with the *@* symbol, followed by a filename containing the JSON data.
+
+```bash
+curl -d '{"key": "value"}' ...
+curl -d "@data.json" ...
+```
+
+!!! tip
+
+	By default, `-d` will send a `POST` request, so `-X POST` becomes unnecessary.
+
+## Complete Curl example
+
+You should structure most of your requests to the API around this pattern:
+
+```bash
+curl -H "Authorization: bearer ${token}" \
+     -H "Content-Type: application/json" \
+     -d "@data.json" \
+     https://${api-name}-${environment-id}.platform.quix.ai/<action>
+```

docs/apis/intro.md

@@ -0,0 +1,74 @@
+# Quix APIs
+
+The Quix Platform provides several APIs. These are:
+
+* Streaming Writer API
+* Streaming Reader API
+* Portal API
+* Query API
+
+While [Quix Streams](../client-library-intro.md) is the main client library for Quix, there are certain use cases where you need an alternative:
+
+* The client uses a language that is not supported by Quix Streams (Quix Streams supports Python and C# only)
+* There are resource constraints which mean you can't run Quix Streams
+* The nature of the client (for example, a web browser)
+
+In these situations Streaming Reader and Writer APIs can provide an alternative solution - for example, they can easily be accommodated in a modern web browser, or using most modern programming languages with an HTTP or SignalR client. 
+
+Portal API is useful for automating processes normally carried out manually in the Quix Portal.
+
+Query API is useful for testing and examining data persisted into the Quix internal database.
+
+Each of these APIs is described in more detail in the following sections.
+
+## Streaming Writer API
+
+The [Streaming Writer API](./streaming-writer-api/index.md) enables you to stream data into a Quix topic. 
+
+Streaming Writer provides both an HTTP interface and a [SignalR](https://learn.microsoft.com/en-us/aspnet/signalr/overview/getting-started/introduction-to-signalr){target=_blank} interface, with SignalR supporting WebSockets, for real-time data transfer.
+
+* [Read more about Streaming Writer API](./streaming-writer-api/index.md)
+
+## Streaming Reader API
+
+The [Streaming Reader](./streaming-reader-api/index.md) API enables you to stream data out of a Quix topic. 
+
+Streaming Reader uses Microsoft's [SignalR](https://learn.microsoft.com/en-us/aspnet/signalr/overview/getting-started/introduction-to-signalr){target=_blank} technology, which provides both WebSockets and Long Polling, depending on client capabilities.
+
+* [Read more about Streaming Reader API](./streaming-reader-api/index.md)
+
+## Portal API
+
+The [Portal API](portal-api/index.md) gives access to the Quix Portal interface enabling you to automate your project deployment, management and monitoring. For example, you could build command line tools in any language with an HTTP interface available, to create, deploy, and monitor services.
+
+[Read more about Portal API](portal-api/index.md)
+
+## Query API
+
+The [Query API](query-api/index.md) enables you to fetch persisted data from Quix. You can use it for exploring the platform, testing, prototyping applications, or working with persisted data in any language with HTTP capabilities.
+
+!!! note
+
+    Query API was previously known as Data Catalogue API. You may still see occasional references to the Data Catalogue API in the UI and docs.
+
+[Read more about Query API](query-api/index.md)
+
+## Comparing the APIs
+
+Use cases for these APIs are shown in the following table:
+
+| API | Interface | Purpose | Typical use case | Docs link |
+|---|---|---|---|----|
+| Streaming Writer API | HTTP, SignalR (WebSockets) | Publish data to a Quix topic | External service, command line client | [Streaming Writer API](./streaming-writer-api/index.md) | 
+| Streaming Reader API | SignalR (WebSockets and Long Polling)| Subscribe to a Quix topic | Web browser client, dashboard, command line client | [Streaming Reader API](./streaming-reader-api/index.md) |
+| Portal API | HTTP (REST)| Automate Quix | Creating and monitoring deployments | [Portal API](./portal-api/index.md) |
+| Query API | HTTP (REST) | Retrieve persisted data | Evaluate service is processing data correctly | [Query API](./query-api/index.md) |
+
+## Next steps
+
+Read the prerequisites and how to get the API references: 
+
+* Learn about [prerequisites](prerequisites.md)
+* Get the [API references](api-references.md)
+* Learn how to form [HTTP requests](http-requests.md)
+* Set up [SignalR](signalr.md) (if using WebSockets rather than HTTP)

docs/apis/portal-api.md → docs/apis/portal-api/index.md

@@ -2,4 +2,3 @@
 
 The Portal API gives access to the Portal interface enabling you to programmatically control projects, environments, applications, and deployments.
 
-Refer to [Portal API Swagger](https://portal-api.platform.quix.ai/swagger){target=_blank} for more information.

docs/apis/prerequisites.md

@@ -0,0 +1,23 @@
+# Prerequisites
+
+To use the APIs you'll typically need the following:
+
+1. [Sign up to Quix](https://portal.platform.quix.ai/self-sign-up).
+
+2. Obtain a [Personal Access Token](../platform/how-to/personal-access-token-pat.md) - you need this to authenticate requests.
+
+3. [Find out how to get your environment ID](../platform/how-to/get-environment-id.md) - you need this for request URLs.
+
+4. Obtain the [API references](api-references.md).
+
+Useful information can also be found in the settings panels for your environment:
+
+1. Click `Settings` in the bottom left corner of the Quix portal.
+
+2. From `Project settings` select the environment you are working with.
+
+3. Click `APIs and tokens`.
+
+You are now presented with a very useful panel. From here you have useful links to items such as API documentation (rendered with Swagger), as well as your Personal Access Tokens (PATs):
+
+![APIs and tokens](./images/apis-tokens.png){width=80%}

docs/apis/query-api/intro.md → docs/apis/query-api/index.md

@@ -1,19 +1,11 @@
 # Introduction
 
-The Query API allows you to fetch persisted data stored in the Quix platform. You can use it for exploring the platform, prototyping applications, or working with stored data in any language with HTTP capabilities.
+The Query API enables you to fetch persisted data stored in the Quix platform. You can use it for exploring the platform, prototyping applications, or working with stored data in any language with HTTP capabilities.
 
 !!! note
 
     The Query API is primarily designed for **testing purposes only**. For production storage of data, Quix recommends using one of the numerous [connectors](../../platform/connectors/index.md) to persist data in the database technology of your choice.
 
-The API is fully described in our [Swagger documentation](get-swagger.md). Read on for a guide to using the API, including real-world examples you can invoke from your language of choice, or using the command line using `curl`.
-
-## Preparation
-
-Before using any of the endpoints, you’ll need to know how to [authenticate your requests](authenticate.md) and how to [form a typical request to the API](request.md).
-
-You’ll also need to have some data stored in the Quix platform for API use to be meaningful. You can use any Source from our [Code Samples](../../platform/samples/samples.md) to do this using the Quix portal.
-
 ## Further documentation
 
 | Documentation                                | Endpoint           | Examples                                  |