diff --git a/BEST-PRACTICE.md b/BEST-PRACTICE.md index f7a4ab0b..281f7148 100644 --- a/BEST-PRACTICE.md +++ b/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. diff --git a/WRITING-STYLE.md b/WRITING-STYLE.md index 8a167659..ca096f63 100644 --- a/WRITING-STYLE.md +++ b/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: diff --git a/docs/apis/api-references.md b/docs/apis/api-references.md new file mode 100644 index 00000000..6dc2cdfd --- /dev/null +++ b/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-``.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-``.platform.quix.ai/swagger | + +Replace `` 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. diff --git a/docs/apis/http-requests.md b/docs/apis/http-requests.md new file mode 100644 index 00000000..2d85874c --- /dev/null +++ b/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 +``` + +Replace `` 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 " ... +``` + +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://-.platform.quix.ai/ +``` + +So, for example, the endpoint URL for the streaming writer might resemble the following: + +``` +https://writer-acme-weather.platform.quix.ai/ +``` + +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 ` 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/ +``` diff --git a/docs/apis/images/LocationProperties.png b/docs/apis/images/LocationProperties.png deleted file mode 100644 index c9971e2d..00000000 Binary files a/docs/apis/images/LocationProperties.png and /dev/null differ diff --git a/docs/apis/images/Step1.png b/docs/apis/images/Step1.png deleted file mode 100644 index a0f2f416..00000000 Binary files a/docs/apis/images/Step1.png and /dev/null differ diff --git a/docs/apis/images/Step2.png b/docs/apis/images/Step2.png deleted file mode 100644 index 6b53386a..00000000 Binary files a/docs/apis/images/Step2.png and /dev/null differ diff --git a/docs/apis/images/Step3.png b/docs/apis/images/Step3.png deleted file mode 100644 index bca9edd6..00000000 Binary files a/docs/apis/images/Step3.png and /dev/null differ diff --git a/docs/apis/images/Step4.png b/docs/apis/images/Step4.png deleted file mode 100644 index 4f382716..00000000 Binary files a/docs/apis/images/Step4.png and /dev/null differ diff --git a/docs/apis/images/Step5.png b/docs/apis/images/Step5.png deleted file mode 100644 index 47ab0995..00000000 Binary files a/docs/apis/images/Step5.png and /dev/null differ diff --git a/docs/apis/images/Step6.png b/docs/apis/images/Step6.png deleted file mode 100644 index 33b0f735..00000000 Binary files a/docs/apis/images/Step6.png and /dev/null differ diff --git a/docs/apis/images/Step7.png b/docs/apis/images/Step7.png deleted file mode 100644 index 8865cfb8..00000000 Binary files a/docs/apis/images/Step7.png and /dev/null differ diff --git a/docs/apis/images/Step8.png b/docs/apis/images/Step8.png deleted file mode 100644 index e28cadea..00000000 Binary files a/docs/apis/images/Step8.png and /dev/null differ diff --git a/docs/apis/images/apis-tokens.png b/docs/apis/images/apis-tokens.png new file mode 100644 index 00000000..57aa355a Binary files /dev/null and b/docs/apis/images/apis-tokens.png differ diff --git a/docs/apis/images/buttons/topics-button-small.png b/docs/apis/images/buttons/topics-button-small.png deleted file mode 100644 index 5dc4f626..00000000 Binary files a/docs/apis/images/buttons/topics-button-small.png and /dev/null differ diff --git a/docs/apis/images/deploy/car-sim.png b/docs/apis/images/deploy/car-sim.png deleted file mode 100644 index 5f411274..00000000 Binary files a/docs/apis/images/deploy/car-sim.png and /dev/null differ diff --git a/docs/apis/images/deploy/deployment-browse.png b/docs/apis/images/deploy/deployment-browse.png deleted file mode 100644 index 3cf1d9c4..00000000 Binary files a/docs/apis/images/deploy/deployment-browse.png and /dev/null differ diff --git a/docs/apis/images/deploy/deployments.png b/docs/apis/images/deploy/deployments.png deleted file mode 100644 index 4658e2c2..00000000 Binary files a/docs/apis/images/deploy/deployments.png and /dev/null differ diff --git a/docs/apis/images/deploy/new-deployment-public-access.png b/docs/apis/images/deploy/new-deployment-public-access.png deleted file mode 100644 index 84e5b252..00000000 Binary files a/docs/apis/images/deploy/new-deployment-public-access.png and /dev/null differ diff --git a/docs/apis/images/deploy/new-deployment-variables.png b/docs/apis/images/deploy/new-deployment-variables.png deleted file mode 100644 index e7915545..00000000 Binary files a/docs/apis/images/deploy/new-deployment-variables.png and /dev/null differ diff --git a/docs/apis/images/deploy/new-deployment.png b/docs/apis/images/deploy/new-deployment.png deleted file mode 100644 index 522a3d2b..00000000 Binary files a/docs/apis/images/deploy/new-deployment.png and /dev/null differ diff --git a/docs/apis/images/deploy/projects.png b/docs/apis/images/deploy/projects.png deleted file mode 100644 index 4512b866..00000000 Binary files a/docs/apis/images/deploy/projects.png and /dev/null differ diff --git a/docs/apis/images/favicon.ico b/docs/apis/images/favicon.ico deleted file mode 100644 index 931ab999..00000000 Binary files a/docs/apis/images/favicon.ico and /dev/null differ diff --git a/docs/apis/images/icons/data-icon.png b/docs/apis/images/icons/data-icon.png deleted file mode 100644 index f47bf0f4..00000000 Binary files a/docs/apis/images/icons/data-icon.png and /dev/null differ diff --git a/docs/apis/images/icons/expand.jpg b/docs/apis/images/icons/expand.jpg deleted file mode 100644 index dc5f3226..00000000 Binary files a/docs/apis/images/icons/expand.jpg and /dev/null differ diff --git a/docs/apis/images/icons/library-icon.png b/docs/apis/images/icons/library-icon.png deleted file mode 100644 index 94961aa2..00000000 Binary files a/docs/apis/images/icons/library-icon.png and /dev/null differ diff --git a/docs/apis/images/icons/topics.png b/docs/apis/images/icons/topics.png deleted file mode 100644 index 81f3aca0..00000000 Binary files a/docs/apis/images/icons/topics.png and /dev/null differ diff --git a/docs/apis/images/icons/visualize-icon.png b/docs/apis/images/icons/visualize-icon.png deleted file mode 100644 index 114c5d0b..00000000 Binary files a/docs/apis/images/icons/visualize-icon.png and /dev/null differ diff --git a/docs/apis/images/parameterlocationexample.png b/docs/apis/images/parameterlocationexample.png deleted file mode 100644 index 328e7b2f..00000000 Binary files a/docs/apis/images/parameterlocationexample.png and /dev/null differ diff --git a/docs/apis/images/quick-start/create-a-workspace.png b/docs/apis/images/quick-start/create-a-workspace.png deleted file mode 100644 index 97f41b22..00000000 Binary files a/docs/apis/images/quick-start/create-a-workspace.png and /dev/null differ diff --git a/docs/apis/images/quick-start/deploy-completed.png b/docs/apis/images/quick-start/deploy-completed.png deleted file mode 100644 index 58fd9727..00000000 Binary files a/docs/apis/images/quick-start/deploy-completed.png and /dev/null differ diff --git a/docs/apis/images/quick-start/project-checkout-dialog.png b/docs/apis/images/quick-start/project-checkout-dialog.png deleted file mode 100644 index 0b1fbe7e..00000000 Binary files a/docs/apis/images/quick-start/project-checkout-dialog.png and /dev/null differ diff --git a/docs/apis/images/quick-start/pycharm-code-completion.png b/docs/apis/images/quick-start/pycharm-code-completion.png deleted file mode 100644 index 286f196a..00000000 Binary files a/docs/apis/images/quick-start/pycharm-code-completion.png and /dev/null differ diff --git a/docs/apis/images/quick-start/pycharm-quixstreaming-package.png b/docs/apis/images/quick-start/pycharm-quixstreaming-package.png deleted file mode 100644 index 0e1b840f..00000000 Binary files a/docs/apis/images/quick-start/pycharm-quixstreaming-package.png and /dev/null differ diff --git a/docs/apis/images/quick-start/topic-persist.png b/docs/apis/images/quick-start/topic-persist.png deleted file mode 100644 index 4cfd39a0..00000000 Binary files a/docs/apis/images/quick-start/topic-persist.png and /dev/null differ diff --git a/docs/apis/images/quick-start/visualize.png b/docs/apis/images/quick-start/visualize.png deleted file mode 100644 index 370bc4b0..00000000 Binary files a/docs/apis/images/quick-start/visualize.png and /dev/null differ diff --git a/docs/apis/images/quick-start/vscode-code-completion.png b/docs/apis/images/quick-start/vscode-code-completion.png deleted file mode 100644 index 3a171ae3..00000000 Binary files a/docs/apis/images/quick-start/vscode-code-completion.png and /dev/null differ diff --git a/docs/apis/images/quick-start/vscode-python-extension.png b/docs/apis/images/quick-start/vscode-python-extension.png deleted file mode 100644 index d1798356..00000000 Binary files a/docs/apis/images/quick-start/vscode-python-extension.png and /dev/null differ diff --git a/docs/apis/images/quick-start/vscode-python-list.png b/docs/apis/images/quick-start/vscode-python-list.png deleted file mode 100644 index 8bcbee4d..00000000 Binary files a/docs/apis/images/quick-start/vscode-python-list.png and /dev/null differ diff --git a/docs/apis/images/quick-start/vscode-python-version.png b/docs/apis/images/quick-start/vscode-python-version.png deleted file mode 100644 index b1f77941..00000000 Binary files a/docs/apis/images/quick-start/vscode-python-version.png and /dev/null differ diff --git a/docs/apis/images/quick-start/vscode-welcome.png b/docs/apis/images/quick-start/vscode-welcome.png deleted file mode 100644 index 1d97ddf7..00000000 Binary files a/docs/apis/images/quick-start/vscode-welcome.png and /dev/null differ diff --git a/docs/apis/images/visualisationdefinition.png b/docs/apis/images/visualisationdefinition.png deleted file mode 100644 index 4f63c163..00000000 Binary files a/docs/apis/images/visualisationdefinition.png and /dev/null differ diff --git a/docs/apis/images/visualisationdefinitionrangeexample.png b/docs/apis/images/visualisationdefinitionrangeexample.png deleted file mode 100644 index 73007537..00000000 Binary files a/docs/apis/images/visualisationdefinitionrangeexample.png and /dev/null differ diff --git a/docs/apis/index.md b/docs/apis/index.md deleted file mode 100644 index 163b58d1..00000000 --- a/docs/apis/index.md +++ /dev/null @@ -1,19 +0,0 @@ -# Quix APIs - -The Quix Platform provides the following APIs: - -## Query - -The [Query API](query-api/intro.md) allows you to fetch 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. - -## Streaming Writer - -The [Streaming Writer API](streaming-writer-api/intro.md) allows you to stream data into the Quix platform via HTTP. It’s an alternative to using our C\# and Python client libraries. You can use the Streaming Writer API from any HTTP-capable language. - -## Streaming Reader - -As an alternative to the client library, the Quix platform supports real-time data streaming over WebSockets, via the [Streaming Reader API](streaming-reader-api/intro.md). Clients can receive updates on data and definitions for parameters and events, as they happen. The examples use the Microsoft SignalR JavaScript client library. - -## Portal API - -The [Portal API](portal-api.md) gives access to the Portal interface enabling you to programmatically control projects, environments, applications, and deployments. diff --git a/docs/apis/intro.md b/docs/apis/intro.md new file mode 100644 index 00000000..464e0dca --- /dev/null +++ b/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) diff --git a/docs/apis/portal-api.md b/docs/apis/portal-api/index.md similarity index 59% rename from docs/apis/portal-api.md rename to docs/apis/portal-api/index.md index 80803cac..86e1aa22 100644 --- a/docs/apis/portal-api.md +++ b/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. diff --git a/docs/apis/prerequisites.md b/docs/apis/prerequisites.md new file mode 100644 index 00000000..ac46c938 --- /dev/null +++ b/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%} diff --git a/docs/apis/query-api/get-swagger.md b/docs/apis/query-api/get-swagger.md deleted file mode 100644 index a4724970..00000000 --- a/docs/apis/query-api/get-swagger.md +++ /dev/null @@ -1,17 +0,0 @@ -# Getting the Swagger documentation URL - -You can access [Swagger documentation](https://swagger.io/){target=_blank} and then use it to try out the [Query API](intro.md). - -The URL is environment-specific, and follows this pattern: - - https://telemetry-query-${organization}-${environment}.platform.quix.ai/swagger - -The environment ID is a combination based on your organization and environment names. For example, for an `acme` organization with a `weather` environment, the URL would have the following format: - - https://telemetry-query-acme-weather.platform.quix.ai/swagger - -To help determine the URL, you can [find out how to get your environment id](../../platform/how-to/get-environment-id.md). - -!!! tip - - Once you access the Swagger documentation, you can select the version of the API you require from the `Select a definition` dropdown list. diff --git a/docs/apis/query-api/intro.md b/docs/apis/query-api/index.md similarity index 64% rename from docs/apis/query-api/intro.md rename to docs/apis/query-api/index.md index 3d7726a0..f313aa15 100644 --- a/docs/apis/query-api/intro.md +++ b/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 | diff --git a/docs/apis/query-api/request.md b/docs/apis/query-api/request.md deleted file mode 100644 index deaf0280..00000000 --- a/docs/apis/query-api/request.md +++ /dev/null @@ -1,63 +0,0 @@ -# Forming a request - -How you send requests to the Query API will vary depending on the client or language you’re using. But the API still has behavior and expectations that is common across all clients. - -!!! tip - - The examples in this section show how to use the popular [`curl`](https://curl.se/){target=_blank} command line tool. - -## Before you begin - -Sign up for a [free Quix account](https://portal.platform.quix.ai/self-sign-up). - -Read about [authenticating](authenticate.md) with the Query API. - -## Endpoint URLs - -The Query API is available on a per-environment basis, so the subdomain is based on a combination of your organization and environment names. See [How to get a environment ID](../../platform/how-to/get-environment-id.md) to find out how to get the exact hostname required. It will be in this format: - - https://telemetry-query-${organization}-${environment}.platform.quix.ai/ - -So your final endpoint URL will look something like: - - https://telemetry-query-acme-weather.platform.quix.ai/ - -## Method - -Most endpoints use the `POST` method, even those that just fetch data. Ensure your HTTP client sends `POST` requests as appropriate. - -Using `curl`, the `-X POST` flag specifies a POST request. Note that this is optional if you’re using the `-d` flag to send a payload (see below). - -```bash -curl -X POST ... -``` - -## 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 via a POST request 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" ... -``` - -## Complete curl example - -You should structure most of your requests to the API around this pattern: - -```bash -curl -H "Authorization: ${token}" \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - https://${domain}.platform.quix.ai/${endpoint} -``` diff --git a/docs/apis/signalr.md b/docs/apis/signalr.md new file mode 100644 index 00000000..20db1be7 --- /dev/null +++ b/docs/apis/signalr.md @@ -0,0 +1,82 @@ +# Set up SignalR + +[Microsoft SignalR](https://learn.microsoft.com/en-us/aspnet/signalr/overview/getting-started/introduction-to-signalr){target=_blank} enables real-time bi-directional communication between Quix and a client. The underlying transport used is either WebSockets or Long POlling, depending on the client's capabilities. + +You'll use SignalR where you need high speed, real-time, communication between Quix and the client, as typically the request-response model of the HTTP/REST approach does not scale to this use case. + +This page explains how to set up Microsoft SignalR. + +## Installation + +You can install SignalR using `npm` (for Node.js applications) or using a CDN (for web browser applications): + +=== "npm" + + If you are using a package manager such as [npm](https://www.npmjs.com/){target=_blank}, you can install SignalR using: + + ``` shell + npm install @microsoft/signalr + ``` + +=== "CDN" + + You can also install SignalR using a CDN. For example, in HTML: + + ``` html + + + + Hello SignalR + + + ... + + ``` + +## Testing the connection + +Once you’ve installed the SignalR library, you can test it with the following code snippet. This opens a connection to the hub running on your custom subdomain, and checks authentication. + +You should replace the text `YOUR_PAT` with your [PAT](../platform/how-to/personal-access-token-pat.md). + +You should also replace `YOUR_ENVIRONMENT_ID` with your [environment ID](../platform/how-to/get-environment-id.md). + +=== "Writer API" + + ```javascript + var signalR = require("@microsoft/signalr"); + const token = "YOUR_PAT" + const environmentId = "YOUR_ENVIRONMENT_ID" + + const options = { + accessTokenFactory: () => token + }; + + const connection = new signalR.HubConnectionBuilder() + .withUrl("https://writer-" + environmentId + ".platform.quix.ai/hub", options) + .build(); + + connection.start().then(() => console.log("SignalR connected.")); + ``` + +=== "Reader API" + + ```javascript + var signalR = require("@microsoft/signalr"); + + const options = { + accessTokenFactory: () => 'YOUR_PAT' + }; + + const connection = new signalR.HubConnectionBuilder() + .withUrl("https://reader-YOUR_ENVIRONMNENT_ID.platform.quix.ai/hub", options) + .build(); + + connection.start().then(() => console.log("SignalR connected.")); + ``` + +If the connection is successful, you see the console log "SignalR connected". + +!!! tip + + Also available as JsFiddle at [https://jsfiddle.net/QuixAI/L9ha4p5j/](https://jsfiddle.net/QuixAI/L9ha4p5j/){target=_blank} \ No newline at end of file diff --git a/docs/apis/streaming-reader-api/authenticate.md b/docs/apis/streaming-reader-api/authenticate.md deleted file mode 100644 index c9cc4b03..00000000 --- a/docs/apis/streaming-reader-api/authenticate.md +++ /dev/null @@ -1,31 +0,0 @@ -# Authenticate - -## Before you begin - - - Sign up on the Quix Portal - -## Get a Personal Access Token - -You should authenticate requests to the Streaming Reader API using a -Personal Access Token (PAT). This is a time-limited token which you can -revoke if necessary. - -Follow these steps to generate a PAT: - -1. Click the user icon in the top-right of the Portal and select the - Tokens menu. - -2. Click **GENERATE TOKEN**. - -3. Choose a name to describe the token’s purpose, and an expiration - date, then click **CREATE**. - -4. Copy the token and store it in a secure place. - -!!! warning - - You won’t be able to retrieve your token from the Portal once you’ve created it, so make sure to take a copy. - -!!! warning - - Treat your tokens like passwords and keep them secret. When working with the API, use tokens as environment variables instead of hardcoding them into your programs. diff --git a/docs/apis/streaming-reader-api/index.md b/docs/apis/streaming-reader-api/index.md new file mode 100644 index 00000000..296c18aa --- /dev/null +++ b/docs/apis/streaming-reader-api/index.md @@ -0,0 +1,12 @@ +# Introduction + +As an alternative to [Quix Streams](../../client-library-intro.md), the Quix platform supports real-time data streaming over WebSockets (or Long Polling depending on client support). + +Clients can receive updates on data and definitions for parameters and events, as they happen. + +Streaming Reader API is typically used by clients written in languages not supported by Quix Streams (which supports Python and C#), or by other web services and clients that need to subscribe to data from a Quix topic. + +!!! note + + The following examples use the Microsoft [SignalR](https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-5.0){target=_blank} JavaScript client library. + diff --git a/docs/apis/streaming-reader-api/intro.md b/docs/apis/streaming-reader-api/intro.md deleted file mode 100644 index 72303d92..00000000 --- a/docs/apis/streaming-reader-api/intro.md +++ /dev/null @@ -1,16 +0,0 @@ -# Introduction - -As an alternative to [Quix Streams](../../client-library-intro.md), the Quix platform supports real-time data streaming over WebSockets. Clients can receive updates on data and definitions for parameters and events, as they happen. - -The examples shown use the Microsoft -[SignalR](https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-5.0){target=_blank} JavaScript client library. - -## Documentation - - - [Set up SignalR](signalr.md) - - - [Authenticate](authenticate.md) - - - [Reading data](reading-data.md) - - - [Subscription and Event reference](subscriptions.md) diff --git a/docs/apis/streaming-reader-api/reading-data.md b/docs/apis/streaming-reader-api/reading-data.md index 2b3234a0..bacbfcfc 100644 --- a/docs/apis/streaming-reader-api/reading-data.md +++ b/docs/apis/streaming-reader-api/reading-data.md @@ -1,26 +1,25 @@ # Reading data -Before you can read data from a stream, you need to subscribe to an -event of the Streaming Reader service like ParameterData or EventData. +Before you can read data from a stream, you need to subscribe to an event of the Streaming Reader service such as `ParameterData` or `EventData`. -You can get a full list of Subscriptions and Events [here](subscriptions.md) . +Read the [Subscriptions and Events reference guide](subscriptions.md). ## Example -The following code sample shows how to use the SignalR client library -to: +The following code sample shows how to use the SignalR client library to: -1. Establish a connection to Quix +1. Establish a connection to Quix. -2. Subscribe to a parameter data stream +2. Subscribe to a parameter data stream (you can subscribe to multiple streams using the special wildcard character `*`). -3. Receive data from that stream +3. Receive data from that stream. -4. Unsubscribe from the event +4. Unsubscribe from the event. - +In the following Node.js code, click `+` to see the annotation: ``` javascript +// Use with Demo Data (for example) var signalR = require("@microsoft/signalr"); const options = { @@ -28,23 +27,35 @@ const options = { }; const connection = new signalR.HubConnectionBuilder() - .withUrl("https://reader-YOUR_WORKSPACE_ID.platform.quix.ai/hub", options) + .withUrl("https://reader-YOUR_ENVIRONMENT_ID.platform.quix.ai/hub", options) .build(); -// Establish connection +// Establish connection (1) connection.start().then(() => { console.log("Connected to Quix."); - // Subscribe to parameter data stream. + // Subscribe to parameter data stream (2) connection.invoke("SubscribeToParameter", "your-topic-name", "your-stream-id", "your-parameter-id"); - // Read data from the stream. + // Read data from the stream (3) connection.on("ParameterDataReceived", data => { - let model = JSON.parse(data); - console.log("Received data from stream: " + model.streamId); + console.log("topicId: " + data.topicId); + console.log("streamId: " + data.streamId); + console.log("EngineRPM values: " + data.numericValues.EngineRPM); - // Unsubscribe from stream. + // Unsubscribe from stream (4) connection.invoke("UnsubscribeFromParameter", "your-topic-name", "your-stream-id", "your-parameter-id"); }); }); ``` + +1. Establish the connection to Quix. +2. Subscribe to a parameter data stream (you can subscribe to multiple streams using the special wildcard character `*`). +3. Read data from the stream. +4. Unsubscribe from the stream. + +Note that SignalR will confirm its connection method, with logging such as the following: + +``` shell +[2023-10-09T15:23:27.993Z] Information: WebSocket connected to wss://reader-joeengland-apitests-testing.platform.quix.ai/hub?id=ABC9Ctg5zdQ7aAzXYX. +``` diff --git a/docs/apis/streaming-reader-api/signalr.md b/docs/apis/streaming-reader-api/signalr.md deleted file mode 100644 index 54a190d1..00000000 --- a/docs/apis/streaming-reader-api/signalr.md +++ /dev/null @@ -1,46 +0,0 @@ -# Set up SignalR - -## Before you begin - -Get a PAT for [Authentication](authenticate.md). - -Ensure you know your environment ID. - -## Installation - -If you are using a package manager like [npm](https://www.npmjs.com/){target=_blank}, you can install SignalR using `npm install @microsoft/signalr`. For other installation options that don’t depend on a platform like Node.js, such as consuming SignalR from a CDN, please refer to [SignalR documentation](https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-3.1){target=_blank}. - -## Testing the connection - -Once you’ve installed the SignalR library, you can test it’s set up correctly with the following code snippet. This opens a connection to the hub running on your custom subdomain, and checks authentication. - -You should replace the text `YOUR_ACCESS_TOKEN` with the PAT obtained from [Authenticating with the Streaming Reader API](authenticate.md). - -You should also replace `YOUR_ENVIRONMENT_ID` with the appropriate identifier, a combination of your organization and environment names. - -This can be located in one of the following ways: - -- **Portal URL** - Look in the browsers URL when you are logged into the Portal and inside the environment you want to work with. The URL contains the environment ID. For example, everything after "workspace=" through to the next *&* - - !!! note - - `workspace=` is legacy. This is in fact your environment ID. - - -- **Settings** - Click on `Settings` and then the environment. Click on `General settings`. The environment name and environment ID is displayed. - -```javascript -var signalR = require("@microsoft/signalr"); - -const options = { - accessTokenFactory: () => 'YOUR_ACCESS_TOKEN' -}; - -const connection = new signalR.HubConnectionBuilder() - .withUrl("https://reader-YOUR_ENVIRONMNENT_ID.platform.quix.ai/hub", options) - .build(); - -connection.start().then(() => console.log("SignalR connected.")); -``` - -If the connection is successful, you should see the console log "SignalR connected". diff --git a/docs/apis/streaming-reader-api/subscriptions.md b/docs/apis/streaming-reader-api/subscriptions.md index 6b24e892..9bc65d1e 100644 --- a/docs/apis/streaming-reader-api/subscriptions.md +++ b/docs/apis/streaming-reader-api/subscriptions.md @@ -1,116 +1,162 @@ -# Subscription & Event reference +# SignalR subscription and event reference -The Quix SignalR hub provides the following subscriptions and events. +The Quix SignalR hub provides the subscriptions and events. You subscribe to channels of interest, and then you can write code that handles events on that channel if and when they occur. -## Subscriptions +## Subscribe -You can subscribe to the following hub methods via [the `invoke` method](https://docs.microsoft.com/en-gb/javascript/api/@aspnet/signalr/hubconnection?view=signalr-js-latest#invoke){target=_blank} -of a `HubConnection`: +You can subscribe to the following hub methods using [the `invoke` method](https://docs.microsoft.com/en-gb/javascript/api/@aspnet/signalr/hubconnection?view=signalr-js-latest#invoke){target=_blank} of a `HubConnection`: - - `SubscribeToParameter(topicName, streamId, parameterId)`: Subscribe - to a parameter data stream. +| Hub method (C#) | Description | Invocation code (JavaScript) | +|----|----|----| +| `SubscribeToParameter(topicName, streamId, parameterId)` | Subscribe to a parameter data stream | `connection.invoke("SubscribeToParameter", "your-topic-name", "your-stream-id", "your-parameter-id");` | +| `SubscribeToEvent(topicName, streamId, eventId)` | Subscribes to an event data stream | `connection.invoke("SubscribeToEvent", "your-topic-name", "your-stream-id", "your-parameter-id");` | +| `IList SubscribeToActiveStreams(topicName)` | Subscribe to Active Streams List changes. The subscription method returns an initial list of the active streams existing in the topic | `connection.invoke("SubscribeToActiveStreams", "your-topic-name");` | +| `IList SubscribeToTopicMetrics(topicName)` | Subscribe to Topic metrics updates. The subscription method returns an initial list of the last 5 minutes of topic metrics | `connection.invoke("SubscribeToTopicMetrics", "your-topic-name");` | +| `SubscribeToPackages(string topicName)` | Subscribe to Topic packages. A package is an abstraction for any message received in the topic | `connection.invoke("SubscribeToTopicPackages", "your-topic-name");` | - - `SubscribeToEvent(topicName, streamId, eventId)`: Subscribes to an - event data stream. +!!! tip - - `IList SubscribeToActiveStreams(topicName)`: Subscribe - to Active Streams List changes. The subscription method returns an - initial list of the active streams existing in the topic. + When subscribing, you can use the wildcard `*` for topics, streams, and parameters. - - `IList SubscribeToTopicMetrics(topicName)`: Subscribe - to Topic metrics updates. The subscription method returns an initial - list of the last 5 minutes of topic metrics. +## Unsubscribe - - `SubscribeToPackages(string topicName)`: Subscribe to Topic - packages. A package is an abstraction for any message received in - the topic. +Each Subscribe method has its own `Unsubscribe` method. Use them to avoid receiving data unnecessarily. The `Unsubscribe` methods are detailed in the following table: -Each Subscribe method has its own Unsubscribe. Use them once you don’t -need the subscriptions anymore to avoid receiving data unnecessarily: +| Method | Description | +|----|----| +| `UnsubscribeFromParameter(topicName, streamId, parameterId)` | Unsubscribe from a parameter data stream | +| `UnsubscribeFromEvent(topicName, streamId, eventId)` | Unsubscribe from an event data stream | +| `UnsubscribeFromActiveStreams(string topicName)` | Unsubscribe from Streams List changes | +| `UnsubscribeFromTopicMetrics(topicName)` | Unsubscribe from Topic metrics updates | +| `UnsubscribeFromPackages(string topicName)` | Unsubscribe from Topic packages | +| `UnsubscribeFromStream(topicName, streamId)` | Unsubscribes from all subscriptions of the specified stream | - - `UnsubscribeFromParameter(topicName, streamId, parameterId)`: - Unsubscribe from a parameter data stream. +## SignalR events - - `UnsubscribeFromEvent(topicName, streamId, eventId)` Unsubscribe - from an event data stream. +You can register a handler for SignalR events using [the JavaScript `on` method](https://docs.microsoft.com/en-gb/javascript/api/@aspnet/signalr/hubconnection?view=signalr-js-latest#on){target=_blank} of a `HubConnection`. - - `UnsubscribeFromActiveStreams(string topicName)`: Unsubscribe from - Streams List changes. +The following events are available: - - `UnsubscribeFromTopicMetrics(topicName)`: Unsubscribe from Topic - metrics updates. + - `ParameterDataReceived(parameterData)` - - `UnsubscribeFromPackages(string topicName)`: Unsubscribe from Topic - packages. + - `EventDataReceived(eventData)` - - `UnsubscribeFromStream(topicName, streamId)`: Unsubscribes from all - subscriptions of the specified stream. + - `ActiveStreamsChanged(stream, action)` -!!! tip - - You should pass the method’s name as the first argument to `invoke`, followed by the method-specific arguments. For example, to call: + - `TopicMetricsUpdated(metrics)` - `SubscribeToParameter(topicName, streamId, parameterId)` + - `PackageReceived(package)` - Use the following: - ``` javascript - connection.invoke("SubscribeToParameter", "your-topic-name", "your-stream-id", "your-parameter-id"); - ``` +Pass the event’s name as the first argument to the `on` method, followed by a callback function. For example, to react to the `ParameterDataReceived` event, use the following: -## SignalR events +``` javascript +connection.on("ParameterDataReceived", data => { + // process payload data +}); +``` -You can register a handler for SignalR events using [the `on` method](https://docs.microsoft.com/en-gb/javascript/api/@aspnet/signalr/hubconnection?view=signalr-js-latest#on){target=_blank} of a `HubConnection`. The following events are available: +Each of the previously listed methods are described in the following sections. - - `ParameterDataReceived(parameterData)` +### ParameterDataReceived - - `EventDataReceived(eventData)` +Add a listener to `ParameterDataReceived` event to receive parameter data from a `SubscribeToParameter` subscription. - - `ActiveStreamsChanged(stream, action)` +One event is generated each time a `ParameterData`` package is received in the topic and the data contains the parameter the user has subscribed to. - - `TopicMetricsUpdated(metrics)` +A more complete example is shown here: - - `PackageReceived(package)` +``` javascript +var signalR = require("@microsoft/signalr"); -!!! tip +const options = { + accessTokenFactory: () => '' +}; - You should pass the event’s name as the first argument to `on`, followed by a function callback. For example, to react to the `ParameterDataReceived` event, use the following: +const connection = new signalR.HubConnectionBuilder() + .withUrl("https://reader-joeengland-apitests-testing.platform.quix.ai/hub", options) + .build(); - ``` javascript - connection.on("ParameterDataReceived", data => { - // process payload data - }); - ``` +// Establish connection +connection.start().then(() => { + console.log("Connected to Quix."); -### ParameterDataReceived + // Subscribe to parameter data stream + connection.invoke("SubscribeToParameter", "f1-data", "*", "EngineRPM"); -Add a listener to `ParameterDataReceived` event to receive data from a -`SubscribeToParameter` subscription. + // Read parameter data from the stream + connection.on("ParameterDataReceived", data => { + console.log('topicId ', data.topicId); + console.log('streamId ', data.streamId); + console.log('streamId ', data.numericValues.EngineRPM); -One event is generated each time a ParameterData package is received in -the Topic and the data contains the Parameter the user has subscribed -for. + // Unsubscribe from stream + connection.invoke("UnsubscribeFromParameter", "f1-data", "*", "EngineRPM"); + }); +}); +``` Example payload: -``` javascript +``` shell { - topicName: 'topic-1', - streamId: 'b45969d2-4624-4ab7-9779-c8f90ce79420', - timestamps: [ 1591733989000000000, 1591733990000000000, 1591733991000000000 ], - numericValues: { ParameterA: [ 1, 2, 3 ] }, - stringValues: {}, - tagValues: { ParameterA: [ null, null, 'tag-1' ] } + topicId: 'joeengland-apitests-testing-f1-data', + topicName: 'f1-data', + streamId: '020aee7e-edba-4913-aee3-b1e493c78132', + epoch: 0, + timestamps: [ 1697025689418406000, 1697025689487857000 ], + numericValues: { EngineRPM: [ 11444, 11463 ] }, + stringValues: {}, + tagValues: { + DriverStatus: [ 'Flying_lap', 'Flying_lap' ], + LapNumber: [ '2', '2' ], + LapValidity: [ 'Valid', 'Valid' ], + PitStatus: [ 'None', 'None' ], + Sector: [ '0', '0' ], + streamId: [ + '5a517ca4-efc3-4166-aedb-a5c57e2b9c59', + '5a517ca4-efc3-4166-aedb-a5c57e2b9c59' + ] + }, + binaryValues: {} } ``` ### EventDataReceived -Add a listener to `EventDataReceived` event to receive data from a -`SubscribeToEvent` subscription. +Add a listener to `EventDataReceived` event to receive data from a `SubscribeToEvent` subscription. + +One event is generated each time a EventData package is received in the topic and the data contains the event the user has subscribed for. + +A more complete example is shown here: + +``` javascript +var signalR = require("@microsoft/signalr"); + +const options = { + accessTokenFactory: () => '' +}; + +const connection = new signalR.HubConnectionBuilder() + .withUrl("https://reader-joeengland-apitests-testing.platform.quix.ai/hub", options) + .build(); + +// Establish connection +connection.start().then(() => { + console.log("Connected to Quix."); + + // Subscribe to event data stream + connection.invoke("SubscribeToEvent", "topic-1", "*", "EventA"); + + // Read event data from the stream + connection.on("EventDataReceived", data => { + console.log('data --> ', data); -One event is generated each time a EventData package is received in the -Topic and the data contains the Event the user has subscribed for. + // Unsubscribe from stream + connection.invoke("UnsubscribeFromEvent", "topic-1", "*", "EventA"); + }); +}); +``` Example payload: @@ -127,27 +173,81 @@ Example payload: } ``` -### ActiveStreamChanged - -This event is generated each time a change has been produced in the list -of Active streams of a Topic. +### ActiveStreamsChanged -Add a listener to `ActiveStreamChanged` event to receive data from a -`SubscribeToActiveStreams` subscription. This SignalR event contains 2 -arguments on it: +This event is generated each time a change has been produced in the list of active streams in a topic. - - `stream`: Payload of the stream that has been changed. +Add a listener to `ActiveStreamsChanged` event to receive data from a `SubscribeToActiveStreams` subscription. This SignalR event returns two callback parameters: - - `action`: It describes the type of operation has been applied to the - list of active streams: - - - `AddUpdate`: Stream added or updated - - - `Remove`: Stream removed +| Callback Parameter | Description | +|----|----| +| `stream` | Payload of the stream that has been changed | +| `action` | It describes the type of operation has been applied to the list of active streams. Two actions are possible: `AddUpdate`: Stream added or updated. `Remove`: Stream has been removed. | -Stream payload example: +Example code: ``` javascript +var signalR = require("@microsoft/signalr"); + +const options = { + accessTokenFactory: () => '' +}; + +const connection = new signalR.HubConnectionBuilder() + .withUrl("https://reader-joeengland-apitests-testing.platform.quix.ai/hub", options) + .build(); + +// Establish connection +connection.start().then(() => { + console.log("Connected to Quix."); + + connection.invoke("SubscribeToActiveStreams", "f1-data"); + + connection.on("ActiveStreamsChanged", (stream, action) => { + console.log('stream -----> ', stream); + console.log('action -----> ', action); + + }); +}); +``` + +Might produce the following output: + +``` shell +[2023-10-09T15:23:27.993Z] Information: WebSocket connected to wss://reader-joeengland-apitests-testing.platform.quix.ai/hub?id=o9Ctg5zdQ7aAzdQ2Cz4eMw. +Connected to Quix. +stream -----> { + streamId: '0a23798f-7d75-413d-9031-8d8386c2f8c7', + topicId: 'joeengland-apitests-testing-f1-data', + topicName: 'f1-data', + metadata: {}, + parents: [], + parameters: { + EngineTemp: { dataType: 'Numeric' }, + Motion_WorldPositionX: { dataType: 'Numeric' }, + Steer: { dataType: 'Numeric' }, + Brake: { dataType: 'Numeric' }, + EngineRPM: { dataType: 'Numeric' }, + Motion_WorldPositionZ: { dataType: 'Numeric' }, + TotalLapDistance: { dataType: 'Numeric' }, + LapDistance: { dataType: 'Numeric' }, + Gear: { dataType: 'Numeric' }, + original_timestamp: { dataType: 'Numeric' }, + Motion_WorldPositionY: { dataType: 'Numeric' }, + Speed: { dataType: 'Numeric' } + }, + events: {}, + firstSeen: '2023-10-09T15:23:29.7197985Z', + lastSeen: '2023-10-09T15:23:29.7198602Z', + status: 'Receiving', + lastData: '2023-10-09T15:23:29.7198603Z' +} +action -----> AddUpdate +``` + +Another stream payload example, showing more metadata: + +``` json { "streamId": "5ecfc7ce-906c-4d3a-811c-a85ea75a24b3", "topicName": "f1-data", @@ -233,44 +333,93 @@ Stream payload example: ### TopicMetricsUpdated -This event is generated periodically by the service to provide basic -metrics about a Topic, like "Bytes per Second" or "Number of Active -Streams". +This event is generated periodically by the service to provide basic metrics about a Topic, like "Bytes per Second" or "Number of Active Streams". -Add a listener to `TopicMetricsUpdated` event to receive data from a -`SubscribeToTopicMetrics` subscription. +Add a listener to `TopicMetricsUpdated` event to receive data from a `SubscribeToTopicMetrics` subscription. -Topic Metrics payload example: +Example code: ``` javascript +var signalR = require("@microsoft/signalr"); + +const options = { + accessTokenFactory: () => '' +}; + +const connection = new signalR.HubConnectionBuilder() + .withUrl("https://reader-joeengland-apitests-testing.platform.quix.ai/hub", options) + .build(); + +// Establish connection +connection.start().then(() => { + console.log("Connected to Quix."); + + connection.invoke("SubscribeToTopicMetrics", "f1-data"); + + connection.on("TopicMetricsUpdated", (metrics) => { + console.log('metrics -----> ', metrics); + }); +}); +``` + +Topic Metrics payload examples: + +``` shell { - "timestamp": "2022-04-10T19:26:49.1417825Z", - "topicName": "f1-data", - "bytesPerSecond": 14877, - "activeStreams": 1 + timestamp: '2023-10-11T10:22:14.7787333Z', + topicId: 'joeengland-apitests-testing-f1-data', + topicName: 'f1-data', + bytesPerSecond: 8282, + activeStreams: 1 } ``` ### PackageReceived -Add a listener to `PackageReceived` event to receive data from a -`SubscribeToPackages` subscription. +Add a listener to `PackageReceived` event to receive data from a `SubscribeToPackages` subscription. + +One event is generated each time a package is received in the topic. The package contains: + +| Parameter | Description | +|----|----| +| Type | Indicates the Quix client library model used to deserialize the package | +| Value | Deserialized package object represented as a JSON string format | -One event is generated each time a package is received in the topic. +Example code: - - Type: Indicates the Quix Sdk model used to deserialize the package. +``` javascript +var signalR = require("@microsoft/signalr"); + +const options = { + accessTokenFactory: () => '' +}; + +const connection = new signalR.HubConnectionBuilder() + .withUrl("https://reader-joeengland-apitests-testing.platform.quix.ai/hub", options) + .build(); + +// Establish connection +connection.start().then(() => { + console.log("Connected to Quix."); - - Value: Deserialized package object represented as a Json string - format. + connection.invoke("SubscribeToPackages", "f1-data"); + + connection.on("PackageReceived", (package) => { + console.log('package -----> ', package); + }); +}); + +``` Package payload example: -``` javascript +``` shell { - "topicName": "f1-data", - "streamId": "dec481d7-7ae4-403a-9d20-a1cabdcd3275", - "type": "Quix.Sdk.Process.Models.ParameterDataRaw", - "value": "{\"Epoch\":0,\"Timestamps\":[1649623155716050700],\"NumericValues\":{\"LapDistance\":[542.504638671875],\"TotalLapDistance\":[4368.53271484375]},\"StringValues\":{},\"BinaryValues\":{},\"TagValues\":{\"LapValidity\":[\"Valid\"],\"LapNumber\":[\"2\"],\"PitStatus\":[\"None\"],\"Sector\":[\"0\"],\"DriverStatus\":[\"Flying_lap\"]}}", - "dateTime": "2022-04-10T20:39:16.63Z" + topicId: 'joeengland-apitests-testing-f1-data', + topicName: 'f1-data', + streamId: '020aee7e-edba-4913-aee3-b1e493c78132', + type: 'QuixStreams.Telemetry.Models.TimeseriesDataRaw', + value: '{"Epoch":0,"Timestamps":[1697020374684026880,1697020374737754880],"NumericValues":{"original_timestamp":[1.6871805934271606E+18,1.6871805934782164E+18],"Motion_WorldPositionZ":[-47.103004455566406,-51.53349304199219],"Motion_WorldPositionY":[91.16168212890624,91.1617202758789],"Motion_WorldPositionX":[-386.4772338867188,-386.242431640625],"TotalLapDistance":[7836.7548828125,7841.19189453125],"Steer":[0.0,0.0],"Speed":[312.0,312.0],"LapDistance":[184.69873046875,189.1357421875],"Gear":[8.0,8.0],"EngineTemp":[90.0,90.0],"EngineRPM":[11143.0,11153.0],"Brake":[0.0,0.0]},"StringValues":{},"BinaryValues":{},"TagValues":{"DriverStatus":["Flying_lap","Flying_lap"],"LapNumber":["3","3"],"LapValidity":["Valid","Valid"],"PitStatus":["None","None"],"Sector":["0","0"],"streamId":["5a517ca4-efc3-4166-aedb-a5c57e2b9c59","5a517ca4-efc3-4166-aedb-a5c57e2b9c59"]}}', + dateTime: '2023-10-11T10:32:54' } ``` diff --git a/docs/apis/streaming-writer-api/authenticate.md b/docs/apis/streaming-writer-api/authenticate.md deleted file mode 100644 index a072140e..00000000 --- a/docs/apis/streaming-writer-api/authenticate.md +++ /dev/null @@ -1,52 +0,0 @@ -# Authenticate - -## Before you begin - - - Sign up on the Quix Portal - -## Get a Personal Access Token - -You should authenticate requests to the Streaming Writer API using a -Personal Access Token (PAT). This is a time-limited token which you can -revoke if necessary. - -Follow these steps to generate a PAT: - -1. Click the user icon in the top-right of the Portal and select the - Tokens menu. - -2. Click **GENERATE TOKEN**. - -3. Choose a name to describe the token’s purpose, and an expiration - date, then click **CREATE**. - -4. Copy the token and store it in a secure place. - -!!! warning - - You won’t be able to retrieve your token from the Portal once you’ve created it, so make sure to take a copy. - -!!! warning - - Treat your tokens like passwords and keep them secret. When working with the API, use tokens as environment variables instead of hardcoding them into your programs. - -## Sign all your requests using this token - -Make sure you accompany each request to the API with an `Authorization` -header using your PAT as a bearer token, as follows: - -``` http -Authorization: bearer -``` - -Replace `` with your Personal Access Token. 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 " ... -``` - -!!! warning - - If you fail to send a valid Authorization header, the API will respond with a `401 UNAUTHORIZED` status code. diff --git a/docs/apis/streaming-writer-api/create-stream.md b/docs/apis/streaming-writer-api/create-stream.md index 8ec8d390..2fafd79d 100644 --- a/docs/apis/streaming-writer-api/create-stream.md +++ b/docs/apis/streaming-writer-api/create-stream.md @@ -1,45 +1,40 @@ # Create a new Stream -You can create a new stream by specifying a topic to create it in, and supplying any other additional properties required. +Data is typicaly published to a stream within a topic. As a stream is confined to a topic partition, order of delivery is guaranteed for a stream. !!! tip - This method is optional. You can also create a stream implicitly by sending data to a stream that doesn’t already exist. But creating a stream using the method on this page avoids having to determine a unique stream id yourself. + This method is optional. You can also create a stream implicitly by sending data to a stream that doesn’t already exist. If a stream does not exist it is created for you. -## Before you begin - - - You should have an [environment set up](../../platform/glossary.md#environment) with at least one [Topic](../../platform/glossary.md#topics). - - - [Get a Personal Access Token](authenticate.md) to authenticate each request. - -## Using the /streams endpoint +## Using the `/streams` endpoint To create a new stream, send a `POST` request to: /topics/${topicName}/streams -You should replace `$\{topicName}` in the endpoint URL with the name of the [Topic](../../platform/glossary.md#topics) you wish to create the stream in. For example, if your topic is named “cars”, your endpoint URL will be `/topics/cars/streams`. +You should replace `${topicName}` in the endpoint URL with the name of the [Topic](../../platform/glossary.md#topics) you wish to create the stream in. For example, if your topic is named "cars", your endpoint URL will be `/topics/cars/streams`. ### Example request You can create a new Stream with an absolute minimum of effort by passing an empty JSON object in the payload: - - curl +=== "Curl" - ```shell + ``` shell curl "https://${domain}.platform.quix.ai/topics/${topicName}/streams" \ - -H "Authorization: bearer ${token}" \ - -H "Content-Type: application/json" \ - -d '{}' + -X POST \ + -H "Authorization: bearer ${token}" \ + -H "Content-Type: application/json" \ + -d '{}' ``` - - Node.js +=== "Node.js" - ```javascript + ``` javascript const https = require('https'); - + const data = "{}"; - + const options = { hostname: domain + '.platform.quix.ai', path: '/topics/' + topicName + '/streams', @@ -49,29 +44,25 @@ You can create a new Stream with an absolute minimum of effort by passing an emp 'Content-Type': 'application/json' } }; - + const req = https.request(options, res => { res.on('data', d => { let streamId = JSON.parse(d).streamId; console.log(streamId); }); }); - + req.write(data); req.end(); ``` For most real-world cases, you’ll also want to provide some or all of the following: - - `name` - - - `location` - - - `metadata` - - - `parents` - - - `timeOfRecording` +* `name` - the human friendly name of the stream +* `location` - the location of the stream's persisted data in the data catalogue (retrieved using Query API) +* `metadata` - metadata for the stream (retrieved using Query API, or Data Explorer) +* `parents` - the list of stream ids of the parent streams +* `timeOfRecording` - the datetime of the stream recording For example, here’s a more useful payload: @@ -87,7 +78,7 @@ For example, here’s a more useful payload: ### Example response -The JSON returned is an object with a single property, `streamId`. This contains the unique identifier of your newly created stream, and will look something like this: +The JSON returned is an object with a single property, `streamId`. This contains the unique identifier of your newly created stream, and resembles the following: ```json { @@ -99,7 +90,7 @@ The JSON returned is an object with a single property, `streamId`. This contains If you’re following these guides in order, you’ll want to take note of that stream id. For curl examples, it’s convenient to keep it in an environment variable, for example: - ```bash + ``` bash $ streamId=66fb0a2f-eb70-494e-9df7-c06d275aeb7c ``` @@ -143,3 +134,7 @@ connection.start().then(async () => { !!! tip Also available as JsFiddle at [https://jsfiddle.net/QuixAI/cLno68fs/](https://jsfiddle.net/QuixAI/cLno68fs/){target=_blank} + +## 🏃‍♀️ Next step + +[Stream metadata :material-arrow-right-circle:{ align=right }](stream-metadata.md) diff --git a/docs/apis/streaming-writer-api/get-swagger.md b/docs/apis/streaming-writer-api/get-swagger.md deleted file mode 100644 index f514d0a1..00000000 --- a/docs/apis/streaming-writer-api/get-swagger.md +++ /dev/null @@ -1,17 +0,0 @@ -# Getting the Swagger documentation URL - -You can access [Swagger documentation](https://swagger.io/){target=_blank} and then use it to try out the [Streaming Writer API](intro.md). - -The URL is environment-specific, and follows this pattern: - - https://writer-${organization}-${environment}.platform.quix.ai/swagger - -The environment ID is a combination based on your organization and environment names. For example, for an `acme` organization with a `weather` environment, the URL would have the following format: - - https://writer-acme-weather.platform.quix.ai/swagger - -To help determine the URL, you can [find out how to get your environment ID](../../platform/how-to/get-environment-id.md). - -!!! tip - - Once you access the Swagger documentation, you can select the version of the API you require from the `Select a definition` dropdown list. diff --git a/docs/apis/streaming-writer-api/index.md b/docs/apis/streaming-writer-api/index.md new file mode 100644 index 00000000..c1725bbd --- /dev/null +++ b/docs/apis/streaming-writer-api/index.md @@ -0,0 +1,9 @@ +# Introduction + +The Streaming Writer API enables you to stream data into a Quix topic using HTTP endpoints or Microsoft's [SignalR](https://learn.microsoft.com/en-us/aspnet/signalr/overview/getting-started/introduction-to-signalr){target=_blank} technology. You can use the Streaming Writer API from any language or web client with an HTTP (REST) or WebSockets interface. + +Streaming Writer API is typically used by clients written in languages not supported by Quix Streams (which supports Python and C#), or by other web services and clients that need to publish data to Quix. + +## 🏃‍♀️ Next step + +[Create stream :material-arrow-right-circle:{ align=right }](create-stream.md) diff --git a/docs/apis/streaming-writer-api/intro.md b/docs/apis/streaming-writer-api/intro.md deleted file mode 100644 index 777b8fdd..00000000 --- a/docs/apis/streaming-writer-api/intro.md +++ /dev/null @@ -1,31 +0,0 @@ -# Introduction - -The Streaming Writer API allows you to stream data into the Quix platform via HTTP endpoints or SignalR. It’s an alternative to using our C# and Python client libraries. You can use the Streaming Writer API from any HTTP-capable language. - -The API is fully documented 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 - -If you plan on using the HTTP endpoints, then you’ll need to know how to -[authenticate your requests](authenticate.md) -and how to [form a typical request to the API](request.md). - -If you would rather use the SignalR api, which is suggested for high -frequency data streaming, then see [SignalR setup](../streaming-reader-api/signalr.md). - -## Topics covered - - - Stream - - - [Create a new Stream](create-stream.md) - - - [Add Stream metadata](stream-metadata.md) - - - Parameters - - - [Send Parameter data](send-data.md) - - - Events - - - [Send an Event](send-event.md) diff --git a/docs/apis/streaming-writer-api/request.md b/docs/apis/streaming-writer-api/request.md deleted file mode 100644 index d4d45941..00000000 --- a/docs/apis/streaming-writer-api/request.md +++ /dev/null @@ -1,67 +0,0 @@ -# Forming a request - -How you send requests to the Streaming Writer API will vary depending on the client or language you’re using. But the API still has behavior and expectations that is common across all clients. - -!!! tip - - The examples in this section show how to use the popular [`curl`](https://curl.se/ {target=_blank} command line tool. - -## Before you begin - - - Sign up on the Quix Portal - - - Read about [Authenticating with the Streaming Writer API](authenticate.md) - -## Endpoint URLs - -The Streaming Writer API is available on a per-environment basis, so the subdomain is based on a combination of your organization and environment names. See the [Swagger documentation](get-swagger.md) to find out how to get the exact hostname required. It will be in this format: - -https://writer-${organization}-${environment}.platform.quix.ai - -So your final endpoint URL will look something like: - -https://writer-acme-weather.platform.quix.ai/ - -## Method - -Endpoints in this API use the `POST` and `PUT` methods. Ensure your HTTP client sends the correct request method. - -Using `curl`, you can specify the request method with the `-X ` 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: ${token}" \ - -H "Content-Type: application/json" \ - -d "@data.json" \ - https://${domain}.platform.quix.ai/${endpoint} -``` diff --git a/docs/apis/streaming-writer-api/send-data.md b/docs/apis/streaming-writer-api/send-data.md index 528ab807..0bc331c1 100644 --- a/docs/apis/streaming-writer-api/send-data.md +++ b/docs/apis/streaming-writer-api/send-data.md @@ -2,14 +2,6 @@ You can send telemetry data using the Streaming Writer API. Select a topic and a stream to send the data to. In your payload, you can include numeric, string, or binary parameter data, with nanosecond-level timestamps. -## Before you begin - - - You should have an [environment set up](../../platform/glossary.md#environment) with at least one [Topic](../../platform/glossary.md#topics). - - - [Get a Personal Access - Token](authenticate.md) to authenticate each - request. - ## Sending structured data to the endpoint Send a POST request together with a JSON payload representing the data you’re sending to: @@ -18,7 +10,7 @@ Send a POST request together with a JSON payload representing the data you’re /topics/${topicName}/streams/${streamId}/parameters/data ``` -You should replace `$\{topicName}` with the name of the topic your stream belongs to, and `$ {streamId}` with the id of the stream you wish to send data to. For example: +You should replace `${topicName}` with the name of the topic your stream belongs to, and `${streamId}` with the id of the stream you wish to send data to. For example: ``` /topics/cars/streams/66fb0a2f-eb70-494e-9df7-c06d275aeb7c/parameters/data @@ -26,7 +18,7 @@ You should replace `$\{topicName}` with the name of the topic your stream belong !!! tip - You can create a new stream by supplying a `$\{streamId}` that doesn’t already exist. This avoids the need to call the [create stream endpoint](create-stream.md) separately. + You can create a new stream by supplying a `${streamId}` that doesn’t already exist. This avoids the need to call the [create stream endpoint](create-stream.md) separately. ### Example request @@ -42,15 +34,16 @@ Your payload should include an array of `timestamps` with one timestamp for each } ``` -Any data types that are unused can be omitted. So a final request using curl might look something like this: +Any data types that are unused can be omitted. An example request is as follows: === "curl" ``` bash - curl -X POST "https://${domain}.platform.quix.ai/topics/${topicName}/streams/${streamId}/parameters/data" \ - -H "Authorization: Bearer ${token}" \ - -H "Content-Type: application/json" \ - -d '{ + curl "https://${domain}.platform.quix.ai/topics/${topicName}/streams/${streamId}/parameters/data" \ + -X POST \ + -H "Authorization: Bearer ${token}" \ + -H "Content-Type: application/json" \ + -d '{ "timestamps": [1591733989000000000, 1591733990000000000, 1591733991000000000], "numericValues": { "SomeParameter1": [10.01, 202.02, 303.03], @@ -94,6 +87,8 @@ No payload is returned from this call. A 200 HTTP response code indicates succes ## Using SignalR +The following code shows how to send data using SignalR (WebSockets): + ```javascript var signalR = require("@microsoft/signalr"); const token = "YOUR_TOKEN" @@ -160,4 +155,9 @@ connection.start().then(async () => { !!! tip - Also available as JsFiddle at [https://jsfiddle.net/QuixAI/a41b8x0t/](https://jsfiddle.net/QuixAI a41b8x0t/){target=_blank} \ No newline at end of file + Also available as JsFiddle at [https://jsfiddle.net/QuixAI/a41b8x0t/](https://jsfiddle.net/QuixAI a41b8x0t/){target=_blank} + + +## 🏃‍♀️ Next step + +[Send event data :material-arrow-right-circle:{ align=right }](send-event.md) diff --git a/docs/apis/streaming-writer-api/send-event.md b/docs/apis/streaming-writer-api/send-event.md index a0e4f406..23f41672 100644 --- a/docs/apis/streaming-writer-api/send-event.md +++ b/docs/apis/streaming-writer-api/send-event.md @@ -2,13 +2,6 @@ You can add Events to your stream data to record discrete actions for future reference. -## Before you begin - - - [Get a Personal Access Token](authenticate.md) to authenticate each - request. - - - If you don’t already have a Stream in your environment, [add one using the API](create-stream.md). - ## Sending event data To send event data to a stream, use the `POST` method with this endpoint: @@ -25,21 +18,18 @@ You should replace `${topicName}` with the name of the topic your stream belongs !!! tip - You can create a new stream by supplying a `$\{streamId}` that doesn’t already exist. This avoids the need to call the [create stream endpoint](create-stream.md) separately. + You can create a new stream by supplying a `${streamId}` that doesn’t already exist. This avoids the need to call the [create stream endpoint](create-stream.md) separately. Your payload should be an array of events. Each event is an object containing the following properties: - - `id` - a unique identifier for the event - - - `timestamp` - the nanosecond-precise timestamp at which the event occurred - - - `tags` - a object containing key-value string pairs representing tag values - - - `value` - a string value associated with the event +* `id` - a unique identifier for the event +* `timestamp` - the nanosecond-precise timestamp at which the event occurred +* `tags` - a object containing key-value string pairs representing tag values +* `value` - a string value associated with the event ### Example request -This example call adds a single event to a stream. The event has an example value and demonstrates use of a tag to include additional information. +This example call adds a single event to a stream. The event has an example value and demonstrates use of a tag to include additional information: === "curl" @@ -89,10 +79,12 @@ This example call adds a single event to a stream. The event has an example valu ### Response -No payload is returned from this call. A 200 HTTP response code indicates success. If the call fails, you should see either a 4xx or 5xx response code indicating what went wrong. +No payload is returned from this call. A 200 HTTP response code indicates success. If the call fails, you see either a 4xx or 5xx response code, indicating what went wrong. ## Using SignalR +The following code shows how to send event data using SignalR (WebSockets): + ```javascript var signalR = require("@microsoft/signalr"); const token = "YOUR_TOKEN" diff --git a/docs/apis/streaming-writer-api/signalr.md b/docs/apis/streaming-writer-api/signalr.md deleted file mode 100644 index 82662600..00000000 --- a/docs/apis/streaming-writer-api/signalr.md +++ /dev/null @@ -1,46 +0,0 @@ -# Set up SignalR - -## Before you begin - - - Get a PAT for - [Authentication](authenticate.md) - - - Ensure you know your environment ID - -## Installation - -If you are using a package manager like [npm](https://www.npmjs.com/){target=_blank}, you can install SignalR using `npm install @microsoft/signalr`. For other installation options that don’t depend on a platform like Node.js, such as consuming SignalR from a CDN, please refer to [SignalR documentation](https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-3.1){target=_blank}. - -## Testing the connection - -Once you’ve installed the SignalR library, you can test it’s set up correctly with the following code snippet. This opens a connection to the hub running on your custom subdomain, and checks authentication. - -You should replace the text `YOUR_ACCESS_TOKEN` with the PAT obtained from [Authenticating with the Streaming Writer API](authenticate.md). - -You should also replace `YOUR_ENVIRONMENT_ID` with the appropriate identifier, a combination of your organization and environment names. This can be located in one of the following ways: - - - **Portal URL** - Look in the browser's URL when you are logged into the Portal and inside the environment you want to work with. The URL contains the environment ID. For example, everything after `workspace=` till the next *&*. Note, the use of `workspace` here is a legacy term. - - - **Settings** - Click on `Settings` and then the environment. Click on `General settings`. The environment name and environment ID is displayed. - -```javascript -var signalR = require("@microsoft/signalr"); -const token = "YOUR_TOKEN" -const environmentId = "YOUR_ENVIRONMENT_ID" - -const options = { - accessTokenFactory: () => token -}; - -const connection = new signalR.HubConnectionBuilder() - .withUrl("https://writer-" + environmentId + ".platform.quix.ai/hub", options) - .build(); - -connection.start().then(() => console.log("SignalR connected.")); -``` - -If the connection is successful, you should see the console log "SignalR connected". - -!!! tip - - Also available as JsFiddle at [https://jsfiddle.net/QuixAI/L9ha4p5j/](https://jsfiddle.net/QuixAI/L9ha4p5j/){target=_blank} \ No newline at end of file diff --git a/docs/apis/streaming-writer-api/stream-metadata.md b/docs/apis/streaming-writer-api/stream-metadata.md index 34f60257..798b8c9e 100644 --- a/docs/apis/streaming-writer-api/stream-metadata.md +++ b/docs/apis/streaming-writer-api/stream-metadata.md @@ -1,12 +1,6 @@ # Add Stream metadata -You can add arbitrary string metadata to any stream. You can also create a new stream by sending metadata using a stream id that does not already exist. - -## Before you begin - - - You should have an [environment set up](../../platform/glossary.md#environment) with at least one [Topic](../../platform/glossary.md#topics). - - - [Get a Personal Access Token](authenticate.md) to authenticate each request. +You can add arbitrary string metadata to any stream. You can also create a new stream by sending metadata using a stream ID that does not already exist. This is mainly used when retrieving persisted data using the Query API, but is also displayed in Data Explorer. This helps you identify data of interest. ## How to add metadata to a stream @@ -14,13 +8,13 @@ Send a `PUT` request to the following endpoint to update a stream with the given /topics/${topicName}/streams/${streamId} -You should replace `$\{topicName}` with the name of the topic your stream belongs to, and `$\{streamId}` with the id of the stream you wish to update. For example: +You should replace `${topicName}` with the name of the topic your stream belongs to, and `${streamId}` with the id of the stream you wish to update. For example: /topics/cars/streams/66fb0a2f-eb70-494e-9df7-c06d275aeb7c !!! tip - You can create a new stream by supplying a `$\{streamId}` that doesn’t already exist. It will be initialized with the data you provide in the payload, and the id you use in the endpoint. This avoids the need to call the [create stream endpoint](create-stream.md) separately. + You can create a new stream by supplying a `${streamId}` that doesn’t already exist. It will be initialized with the data you provide in the payload, and the ID you use in the endpoint. This avoids the need to call the [create stream endpoint](create-stream.md) separately. Your request should contain a payload consisting of JSON data containing the desired metadata. @@ -115,4 +109,8 @@ connection.start().then(async () => { ``` !!! tip - Also available as JsFiddle at [https://jsfiddle.net/QuixAI/ruywnz28/](https://jsfiddle.net/QuixAI/ruywnz28/){target=_blank} \ No newline at end of file + Also available as JsFiddle at [https://jsfiddle.net/QuixAI/ruywnz28/](https://jsfiddle.net/QuixAI/ruywnz28/){target=_blank} + +## 🏃‍♀️ Next step + +[Send parameter data :material-arrow-right-circle:{ align=right }](send-data.md) diff --git a/docs/index.md b/docs/index.md index 08b6fcb9..4c31c2f4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,50 +6,6 @@ Welcome to the Quix developer documentation! **See [here](./platform/changes.md) for significant recent changes.** -!!! tip - - Our docs support hotkeys. Press ++slash++, ++s++, or ++f++ to activate search, ++p++ or ++comma++ to go to the previous page, ++n++ or ++period++ to go to the next page. - -## See Quix in action - -See the following live demos and running pipelines: - -
- -- __Image processing demo__ - - --- - - See a real-time image processing live demo! - - [:octicons-arrow-right-24: Image processing demo](https://app-demo-computervisiondemo-prod.deployments.quix.ai/){target=_blank} - -- __Image processing pipeline__ - - --- - - See a real-time image processing pipeline running! - - [:octicons-arrow-right-24: Image processing pipeline](https://portal.platform.quix.ai/pipeline?workspace=demo-computervisiondemo-prod&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik1qVTBRVE01TmtJNVJqSTNOVEpFUlVSRFF6WXdRVFF4TjBSRk56SkNNekpFUWpBNFFqazBSUSJ9.eyJodHRwczovL3F1aXguYWkvb3JnX2lkIjoiZGVtbyIsImh0dHBzOi8vcXVpeC5haS9vd25lcl9pZCI6ImF1dGgwfDI4YWQ4NWE4LWY1YjctNGFjNC1hZTVkLTVjYjY3OGIxYjA1MiIsImh0dHBzOi8vcXVpeC5haS90b2tlbl9pZCI6ImMzNzljNmVlLWNkMmYtNDExZC1iOGYyLTMyMDU0ZDc5MTY2YSIsImh0dHBzOi8vcXVpeC5haS9leHAiOiIxNzM3ODI5NDc5LjIyMyIsImlzcyI6Imh0dHBzOi8vYXV0aC5xdWl4LmFpLyIsInN1YiI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBQGNsaWVudHMiLCJhdWQiOiJxdWl4IiwiaWF0IjoxNjk1NzE2MDI4LCJleHAiOjE2OTgzMDgwMjgsImF6cCI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwicGVybWlzc2lvbnMiOltdfQ.Ndm0K2iNHPxDq1ohF-yb-6LzIqx_UY8Ptcq0kAwSNye12S3deX_eDkC4XqZqW2NoSLd3GsmWV9PZGetGGp2IlqshQFZtUMp6WP6hq917ZC1i8JFx93PAbY7NT_88nFDovVlaRcoTpWvI-03KbryLkAoB28c6qb3EFwjCWFBuy_yA4yjQ8uF0-AZ0R9Qi4IBaekXWqcgO0a91gVRg0oA_hnzJFoR-EnZ2G1ZSxtuVgnyyPuQTMUvzJuUT_IJTLzEB_kejX0pcXRZBIwHP8MWLB4mE5DtIdz4jm8WIA4eZJZ7ZCG4dk-adQwZ2BdkNknV5eEwRgRJL4ybaplkaDlR-dg){target=_blank} - -- __Sentiment analysis demo__ - - --- - - See a sentiment analysis live demo! - - [:octicons-arrow-right-24: Sentiment analysis demo](https://sentimentdemoui-demo-chatappdemo-prod.deployments.quix.ai/chat){target=_blank} - -- __Sentiment analysis pipeline__ - - --- - - See a sentiment analysis pipeline running! - - [:octicons-arrow-right-24: Sentiment analysis pipeline](https://portal.platform.quix.ai/pipeline?workspace=demo-chatappdemo-prod&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik1qVTBRVE01TmtJNVJqSTNOVEpFUlVSRFF6WXdRVFF4TjBSRk56SkNNekpFUWpBNFFqazBSUSJ9.eyJodHRwczovL3F1aXguYWkvb3JnX2lkIjoiZGVtbyIsImh0dHBzOi8vcXVpeC5haS9vd25lcl9pZCI6ImF1dGgwfDI4YWQ4NWE4LWY1YjctNGFjNC1hZTVkLTVjYjY3OGIxYjA1MiIsImh0dHBzOi8vcXVpeC5haS90b2tlbl9pZCI6ImMzNzljNmVlLWNkMmYtNDExZC1iOGYyLTMyMDU0ZDc5MTY2YSIsImh0dHBzOi8vcXVpeC5haS9leHAiOiIxNzM3ODI5NDc5LjIyMyIsImlzcyI6Imh0dHBzOi8vYXV0aC5xdWl4LmFpLyIsInN1YiI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBQGNsaWVudHMiLCJhdWQiOiJxdWl4IiwiaWF0IjoxNjk1NzE2MDI4LCJleHAiOjE2OTgzMDgwMjgsImF6cCI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwicGVybWlzc2lvbnMiOltdfQ.Ndm0K2iNHPxDq1ohF-yb-6LzIqx_UY8Ptcq0kAwSNye12S3deX_eDkC4XqZqW2NoSLd3GsmWV9PZGetGGp2IlqshQFZtUMp6WP6hq917ZC1i8JFx93PAbY7NT_88nFDovVlaRcoTpWvI-03KbryLkAoB28c6qb3EFwjCWFBuy_yA4yjQ8uF0-AZ0R9Qi4IBaekXWqcgO0a91gVRg0oA_hnzJFoR-EnZ2G1ZSxtuVgnyyPuQTMUvzJuUT_IJTLzEB_kejX0pcXRZBIwHP8MWLB4mE5DtIdz4jm8WIA4eZJZ7ZCG4dk-adQwZ2BdkNknV5eEwRgRJL4ybaplkaDlR-dg){target=_blank} - -
- ## Get started If you're new to Quix, here are some resources to help get you started quickly. @@ -58,7 +14,7 @@ First, sign up for a [free account](https://portal.platform.quix.ai/self-sign-up
-- __Quickstart__ +- __Quickstart 🚀__ --- @@ -74,40 +30,49 @@ First, sign up for a [free account](https://portal.platform.quix.ai/self-sign-up [:octicons-arrow-right-24: Quix Tour](./platform/quixtour/overview.md) -- __What is Quix?__ +
+ +## See Quix in action + +See the following live demos and running pipelines: + +
+ +- __Image processing demo__ --- - New to Quix? Find out more! + See a real-time image processing live demo! - [:octicons-arrow-right-24: What is Quix?](./platform/what-is-quix.md) + [:octicons-arrow-right-24: Image processing demo](https://app-demo-computervisiondemo-prod.deployments.quix.ai/){target=_blank} -- __Glossary__ +- __Image processing pipeline__ --- - List of Quix terms. + See a real-time image processing pipeline running! - [:octicons-arrow-right-24: Glossary](./platform/glossary.md) - -- __Ingest data__ + [:octicons-arrow-right-24: Image processing pipeline](https://portal.platform.quix.ai/pipeline?workspace=demo-computervisiondemo-prod&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik1qVTBRVE01TmtJNVJqSTNOVEpFUlVSRFF6WXdRVFF4TjBSRk56SkNNekpFUWpBNFFqazBSUSJ9.eyJodHRwczovL3F1aXguYWkvb3JnX2lkIjoiZGVtbyIsImh0dHBzOi8vcXVpeC5haS9vd25lcl9pZCI6ImF1dGgwfDI4YWQ4NWE4LWY1YjctNGFjNC1hZTVkLTVjYjY3OGIxYjA1MiIsImh0dHBzOi8vcXVpeC5haS90b2tlbl9pZCI6ImMzNzljNmVlLWNkMmYtNDExZC1iOGYyLTMyMDU0ZDc5MTY2YSIsImh0dHBzOi8vcXVpeC5haS9leHAiOiIxNzM3ODI5NDc5LjIyMyIsImlzcyI6Imh0dHBzOi8vYXV0aC5xdWl4LmFpLyIsInN1YiI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBQGNsaWVudHMiLCJhdWQiOiJxdWl4IiwiaWF0IjoxNjk1NzE2MDI4LCJleHAiOjE2OTgzMDgwMjgsImF6cCI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwicGVybWlzc2lvbnMiOltdfQ.Ndm0K2iNHPxDq1ohF-yb-6LzIqx_UY8Ptcq0kAwSNye12S3deX_eDkC4XqZqW2NoSLd3GsmWV9PZGetGGp2IlqshQFZtUMp6WP6hq917ZC1i8JFx93PAbY7NT_88nFDovVlaRcoTpWvI-03KbryLkAoB28c6qb3EFwjCWFBuy_yA4yjQ8uF0-AZ0R9Qi4IBaekXWqcgO0a91gVRg0oA_hnzJFoR-EnZ2G1ZSxtuVgnyyPuQTMUvzJuUT_IJTLzEB_kejX0pcXRZBIwHP8MWLB4mE5DtIdz4jm8WIA4eZJZ7ZCG4dk-adQwZ2BdkNknV5eEwRgRJL4ybaplkaDlR-dg){target=_blank} + +- __Sentiment analysis demo__ --- - Read about some of the many ways you can get your data into Quix. + See a sentiment analysis live demo! - [:octicons-arrow-right-24: Ingest data](./platform/ingest-data.md) + [:octicons-arrow-right-24: Sentiment analysis demo](https://sentimentdemoui-demo-chatappdemo-prod.deployments.quix.ai/chat){target=_blank} -- __Help__ +- __Sentiment analysis pipeline__ --- - If you need any help, please sign up to the [Quix community forum](https://forum.quix.io/){target=_blank}. - - [:octicons-arrow-right-24: Join the Quix community forum](https://forum.quix.io/){target=_blank} + See a sentiment analysis pipeline running! + + [:octicons-arrow-right-24: Sentiment analysis pipeline](https://portal.platform.quix.ai/pipeline?workspace=demo-chatappdemo-prod&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik1qVTBRVE01TmtJNVJqSTNOVEpFUlVSRFF6WXdRVFF4TjBSRk56SkNNekpFUWpBNFFqazBSUSJ9.eyJodHRwczovL3F1aXguYWkvb3JnX2lkIjoiZGVtbyIsImh0dHBzOi8vcXVpeC5haS9vd25lcl9pZCI6ImF1dGgwfDI4YWQ4NWE4LWY1YjctNGFjNC1hZTVkLTVjYjY3OGIxYjA1MiIsImh0dHBzOi8vcXVpeC5haS90b2tlbl9pZCI6ImMzNzljNmVlLWNkMmYtNDExZC1iOGYyLTMyMDU0ZDc5MTY2YSIsImh0dHBzOi8vcXVpeC5haS9leHAiOiIxNzM3ODI5NDc5LjIyMyIsImlzcyI6Imh0dHBzOi8vYXV0aC5xdWl4LmFpLyIsInN1YiI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBQGNsaWVudHMiLCJhdWQiOiJxdWl4IiwiaWF0IjoxNjk1NzE2MDI4LCJleHAiOjE2OTgzMDgwMjgsImF6cCI6ImtyMXU4MGRqRllvUUZlb01nMGhqcXZia29lRkxFRDVBIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwicGVybWlzc2lvbnMiOltdfQ.Ndm0K2iNHPxDq1ohF-yb-6LzIqx_UY8Ptcq0kAwSNye12S3deX_eDkC4XqZqW2NoSLd3GsmWV9PZGetGGp2IlqshQFZtUMp6WP6hq917ZC1i8JFx93PAbY7NT_88nFDovVlaRcoTpWvI-03KbryLkAoB28c6qb3EFwjCWFBuy_yA4yjQ8uF0-AZ0R9Qi4IBaekXWqcgO0a91gVRg0oA_hnzJFoR-EnZ2G1ZSxtuVgnyyPuQTMUvzJuUT_IJTLzEB_kejX0pcXRZBIwHP8MWLB4mE5DtIdz4jm8WIA4eZJZ7ZCG4dk-adQwZ2BdkNknV5eEwRgRJL4ybaplkaDlR-dg){target=_blank}
+ ## Tutorials By following these tutorials, you can learn how to build data-driven apps, and integrate Quix with external systems. @@ -168,7 +133,7 @@ Read more about the Quix Streams Client Library and APIs. Stream data to Quix Kafka topics via HTTP with this API. - [:octicons-arrow-right-24: Learn more](./apis/streaming-writer-api/intro.md) + [:octicons-arrow-right-24: Learn more](./apis/streaming-writer-api/index.md) - __Streaming Reader API__ @@ -176,23 +141,75 @@ Read more about the Quix Streams Client Library and APIs. Work with this API to receive live data in your Web applications from Quix Kafka topics via Websockets. - [:octicons-arrow-right-24: Learn more](./apis/streaming-reader-api/intro.md) + [:octicons-arrow-right-24: Learn more](./apis/streaming-reader-api/index.md) + +- __Portal API__ + + --- + + Automate creation and management of your project and pipeline. + + [:octicons-arrow-right-24: Learn more](./apis/portal-api/index.md) + +- __What is Quix?__ + + --- + + New to Quix? Find out more! + + [:octicons-arrow-right-24: What is Quix?](./platform/what-is-quix.md) + +- __Glossary__ + + --- + + List of Quix terms. -- __Query API__ + [:octicons-arrow-right-24: Glossary](./platform/glossary.md) + +- __Ingest data__ --- - Query historical time series data in Quix using HTTP interface. + Read about some of the many ways you can get your data into Quix. + + [:octicons-arrow-right-24: Ingest data](./platform/ingest-data.md) + +- __Help__ + + --- - [:octicons-arrow-right-24: Learn more](./apis/query-api/intro.md) + If you need any help, please sign up to the [Quix community forum](https://forum.quix.io/){target=_blank}. + + [:octicons-arrow-right-24: Join the Quix community forum](https://forum.quix.io/){target=_blank} ## Documentation changelog -The documentation changelog can be found in the [documentation repository Wiki](https://github.com/quixio/quix-docs/wiki/Docs-Releases). +
+ +- __Changelog__ + + --- + + The documentation changelog can be found in the [documentation repository Wiki](https://github.com/quixio/quix-docs/wiki/Docs-Releases). + + This is in addition to general product changes which are summarized in the [changes documentation](./platform/changes.md). + +
+ +## Secret tip ㊙️ -This is in addition to general product changes which are summarized in the [changes documentation](./platform/changes.md). +
+ +- __Hotkeys__ + + --- + + Our docs support hotkeys. Press ++slash++, ++s++, or ++f++ to activate search, ++p++ or ++comma++ to go to the previous page, ++n++ or ++period++ to go to the next page. + +
## Contribute diff --git a/docs/platform/changes.md b/docs/platform/changes.md index 57ae6b33..d9207eda 100644 --- a/docs/platform/changes.md +++ b/docs/platform/changes.md @@ -127,7 +127,7 @@ See documentation on how to [create an application](../platform/how-to/create-ap An entire Quix pipeline can be described by a `quix.yaml` file. This file is also used to configure resources used by the deployment. -This allows Quix to quickly replicate an entire pipeline and configuration. For example, a pipeline created and tested in one branch, can be quickly duplicated in another branch. +This enables Quix to quickly replicate an entire pipeline and configuration. For example, a pipeline created and tested in one branch, can be quickly duplicated in another branch. ### YAML variables diff --git a/docs/platform/concepts/types-of-transform.md b/docs/platform/concepts/types-of-transform.md index 41b93edf..8c77a357 100644 --- a/docs/platform/concepts/types-of-transform.md +++ b/docs/platform/concepts/types-of-transform.md @@ -2,13 +2,13 @@ Types of transform: -1. Filtering: This pattern involves processing a stream of data and selecting specific records that meet certain criteria. It allows you to filter out irrelevant data and focus on the relevant information. +1. Filtering: This pattern involves processing a stream of data and selecting specific records that meet certain criteria. It enables you to filter out irrelevant data and focus on the relevant information. 2. Aggregation: Aggregation involves combining multiple data records from a stream into a single result. It is useful for calculating summary statistics, such as averages, counts, or maximum/minimum values, over a specific time window or key. 3. Transformation: This pattern involves modifying the structure or content of the data as it flows through the stream. Transformations can include data enrichment, normalization, or any other necessary modifications to prepare the data for downstream processing. -4. Joining: Joining patterns involve combining data from multiple streams based on a common key or attribute. It allows you to correlate information from different sources and create a unified view of the data. +4. Joining: Joining patterns involve combining data from multiple streams based on a common key or attribute. It enables you to correlate information from different sources and create a unified view of the data. 5. Windowing: Windowing involves dividing the data stream into discrete time intervals or windows and performing calculations or aggregations within each window. Windowing enables analysis over a specific period, such as sliding windows, tumbling windows, or session windows. @@ -16,9 +16,9 @@ Types of transform: 7. Pattern matching: Pattern matching involves detecting predefined patterns or sequences of events within a stream. It is useful for identifying complex conditions or anomalies based on specific patterns of data. -8. Splitting and routing: This pattern involves splitting a single stream into multiple substreams based on defined criteria or conditions. It enables parallel processing and allows different components to handle different subsets of the data. +8. Splitting and routing: This pattern involves splitting a single stream into multiple substreams based on defined criteria or conditions. It enables parallel processing and enables different components to handle different subsets of the data. 9. Time series analysis: Time series analysis patterns focus on analyzing and extracting insights from time-dependent data streams. Techniques like forecasting, anomaly detection, and trend analysis are commonly used in time series processing. -10. Fan-out/Fan-in: This pattern involves duplicating a stream and sending it to multiple processing components in parallel (fan-out) and then aggregating the results back into a single stream (fan-in). It allows for scalable and parallel processing of data. +10. Fan-out/Fan-in: This pattern involves duplicating a stream and sending it to multiple processing components in parallel (fan-out) and then aggregating the results back into a single stream (fan-in). It enables scalable and parallel processing of data. diff --git a/docs/platform/glossary.md b/docs/platform/glossary.md index 0a306bef..9cbbb960 100644 --- a/docs/platform/glossary.md +++ b/docs/platform/glossary.md @@ -4,7 +4,7 @@ The following is a list of terms useful when working with Quix and streaming dat ## APIs -In addition to the Quix Streams client library, there are several APIs that you can use with Quix. See the [API landing page](../apis/index.md). +In addition to the Quix Streams client library, there are several APIs that you can use with Quix. See the [API landing page](../apis/intro.md). ## Application @@ -160,7 +160,7 @@ Applications implementing a source, transform, or destination, are connected tog ## Portal API -An [HTTP API](../apis/portal-api.md) used to interact with most portal-related features such as creation of [environments](#environment), users, and [deployments](#deployment). +An [HTTP API](../apis/portal-api/index.md) used to interact with most portal-related features such as creation of [environments](#environment), users, and [deployments](#deployment). ## Producer @@ -174,7 +174,7 @@ A project contains one or more [environments](#environment), so typically you cr ## Query API -The [Query API](../apis/query-api/intro.md) is used to query persisted data. Most commonly used for dashboards, analytics and training ML models. Also useful to call historical data when running an ML model, or to call historical data from an external application. This API is primarily iused for testing and debugging purposes. +The [Query API](../apis/query-api/index.md) is used to query persisted data. Most commonly used for dashboards, analytics and training ML models. Also useful to call historical data when running an ML model, or to call historical data from an external application. This API is primarily iused for testing and debugging purposes. ## Quix Portal @@ -206,11 +206,11 @@ Read more about [streams](../client-library/features/streaming-context.md). ## Streaming Reader API -A [WebSockets API](../apis/streaming-reader-api/intro.md) used to stream any data directly from a topic to an external application. Most commonly used to read the results of a model or service to a real-time web application. Your application **reads** data from Quix Platform. +A [WebSockets API](../apis/streaming-reader-api/index.md) used to stream any data directly from a topic to an external application. Most commonly used to read the results of a model or service to a real-time web application. Your application **reads** data from Quix Platform. ## Streaming Writer API -An [HTTP API](../apis/streaming-writer-api/intro.md) used to send telemetry data from any source to a topic in the Quix platform. It should be used when it is not possible to use [Quix Streams](../client-library-intro.md). Your application **writes** data into Quix Platform. +An [HTTP API](../apis/streaming-writer-api/index.md) used to send telemetry data from any source to a topic in the Quix platform. It should be used when it is not possible to use [Quix Streams](../client-library-intro.md). Your application **writes** data into Quix Platform. ## Time series data diff --git a/docs/platform/how-to/deploy-public-page.md b/docs/platform/how-to/deploy-public-page.md index e5b0617e..29612fd2 100644 --- a/docs/platform/how-to/deploy-public-page.md +++ b/docs/platform/how-to/deploy-public-page.md @@ -1,6 +1,6 @@ # How to deploy a public service -The Quix Platform allows you to deploy public-facing web pages and APIs. +The Quix Platform enables you to deploy public-facing web pages and APIs. This how-to will help to explain the features and options and ensure projects containing public facing web pages and APIs are successful. diff --git a/docs/platform/how-to/get-environment-id.md b/docs/platform/how-to/get-environment-id.md index 18678a01..289f2abd 100644 --- a/docs/platform/how-to/get-environment-id.md +++ b/docs/platform/how-to/get-environment-id.md @@ -1,12 +1,12 @@ # Get environment ID -Occasionally, you’ll need to obtain an ID based on a specific environment. For example, endpoints for the [Query API](../../apis/query-api/intro.md) use a domain with the following pattern: +Occasionally, you’ll need to obtain an ID based on a specific environment. For example, endpoints for the [Query API](../../apis/query-api/index.md) use a domain with the following pattern: https://telemetry-query-${environment-id}.platform.quix.ai/ The environment ID is a combination of your organization and environment names, converted to URL friendly values. -To obtain your environment ID: +## Obtain your environment ID from the URL 1. Go to the [Portal home](https://portal.platform.quix.ai/){target=_blank}. @@ -16,8 +16,34 @@ To obtain your environment ID: https://portal.platform.quix.ai/home?workspace={environment-id} +## Obtain environment ID from settings + +You can also get the environment ID from Settings. Click `Settings` in the bottom-left corner of the portal, select the environment of interest. You can then copy the environment ID (previously known as the workspace ID) from the settings panel, as shown in the following screenshot: + +![Get environment ID from settings](../images/how-to/get-environment-id/get-environment-id-settings.png){width=80%} + +## Example environment ID + +Given the following URL for the environment: + +``` +https://portal.platform.quix.ai/pipeline?workspace=joeengland-apitests-testing +``` + +The environment ID is: + +``` +joeengland-apitests-testing +``` + +The components of the environment ID are as follows: + +| joeengland | The name of the Quix account, known as the organization, in this case the personal account of Joe England | +| apitests | The name of the [project](../glossary.md#project) | +| testing | The name of the [environment](../glossary.md#environment) | + Copy the value for `environment-id` and use it wherever you need an environment ID. !!! note - The `workspace` parameter in the URL `https://portal.platform.quix.ai/home?workspace={environment-id}` is there for legacy reasons, and does in fact indicate an environment. \ No newline at end of file + The `workspace=` parameter in the URL `https://portal.platform.quix.ai/home?workspace={environment-id}` is there for legacy reasons, and does in fact indicate an environment. \ No newline at end of file diff --git a/docs/platform/how-to/ingest-csv.md b/docs/platform/how-to/ingest-csv.md index fcbe4c3f..76f2b2e9 100644 --- a/docs/platform/how-to/ingest-csv.md +++ b/docs/platform/how-to/ingest-csv.md @@ -4,7 +4,7 @@ You may need to load data from a CSV file into a service, as CSV is a very commo ## Using pandas -The pandas library allows the contents of a CSV file to be easily loaded into a pandas dataframe. If this data is to be published to a stream it must have a timestamp. If one is not present in the CSV data, it can be added, but that complicated the code a little. The following example demonstrates loading data from an uploaded CSV file where the data contains a timestamp column: +The pandas library enables the contents of a CSV file to be easily loaded into a pandas dataframe. If this data is to be published to a stream it must have a timestamp. If one is not present in the CSV data, it can be added, but that complicated the code a little. The following example demonstrates loading data from an uploaded CSV file where the data contains a timestamp column: ```python import quixstreams as qx diff --git a/docs/platform/how-to/jupyter-nb.md b/docs/platform/how-to/jupyter-nb.md index 1eb71aae..984f7673 100644 --- a/docs/platform/how-to/jupyter-nb.md +++ b/docs/platform/how-to/jupyter-nb.md @@ -4,7 +4,7 @@ In this documentation, you learn how to use Jupyter Notebook to analyze data per ## Why this is important -Although Quix is a real-time platform, to build real-time in-memory models and data processing pipelines, you need to understand data first. To help with that, Quix offers the option to persist data in topics. This data can be accessed using the [Query API](../../apis/query-api/intro.md). This helps make data discovery and analysis easier. +Although Quix is a real-time platform, to build real-time in-memory models and data processing pipelines, you need to understand data first. To help with that, Quix offers the option to persist data in topics. This data can be accessed using the [Query API](../../apis/query-api/index.md). This helps make data discovery and analysis easier. ## Prerequisites diff --git a/docs/platform/how-to/replay.md b/docs/platform/how-to/replay.md index d2937491..fcaff15c 100644 --- a/docs/platform/how-to/replay.md +++ b/docs/platform/how-to/replay.md @@ -1,6 +1,6 @@ # How to replay data -Quix Platform features a **replay service**. This service allows you to replay persisted data into a topic, as if it were live data. This is very useful for the following use cases: +Quix Platform features a **replay service**. This service enables you to replay persisted data into a topic, as if it were live data. This is very useful for the following use cases: * Testing and debugging connectors and transforms * [Stream reprocessing](https://quix.io/blog/intro-stream-reprocessing-python/?x-craft-preview=VDVjwJTquq&token=7oGSdC9yxYk0zECNUz2RtzJLtGqG-aZB){target=_blank} diff --git a/docs/platform/how-to/testing-data-store.md b/docs/platform/how-to/testing-data-store.md index 81da42c0..71e4df03 100644 --- a/docs/platform/how-to/testing-data-store.md +++ b/docs/platform/how-to/testing-data-store.md @@ -2,7 +2,7 @@ Quix provides a data store for testing and debugging purposes. -While [topics](../glossary.md#topic) do provide a configurable retention time, persisting data into a database provides advantages - for example, you can perform powerful queries to retrieve historical data. This data can be retrieved and displayed using the Data Explorer, or retrieved using the [Query API](../../apis/query-api/intro.md). +While [topics](../glossary.md#topic) do provide a configurable retention time, persisting data into a database provides advantages - for example, you can perform powerful queries to retrieve historical data. This data can be retrieved and displayed using the Data Explorer, or retrieved using the [Query API](../../apis/query-api/index.md). Quix provides a very simple way to persist data in a topic. Simply locate the topic in your topic list, and click the `Persistence` button. diff --git a/docs/platform/how-to/webapps.md b/docs/platform/how-to/webapps.md index 346ad85d..6429b8a9 100644 --- a/docs/platform/how-to/webapps.md +++ b/docs/platform/how-to/webapps.md @@ -1,8 +1,6 @@ # Develop web applications with Quix -Quix can bring real-time web functionality to you client applications. -Following types of applications are good candidates to use Quix as their -data plane. +Quix can bring real-time web functionality to you client applications. Following types of applications are good candidates to use Quix as their data plane. - Dashboard and real-time monitoring applications that show updates as they happen to users like cloud/edge monitoring tools. @@ -15,7 +13,4 @@ data plane. ## Node.js -Node.js applications can update parameter and event definitions and write -data to streams using RESTful APIs. Quix supports WebSockets for clients -that want to receive telemetry data and parameters/events updates in -real-time. Node.js clients must authenticate with Quix using [personal access tokens](../../apis/streaming-reader-api/authenticate.md#get-a-personal-access-token). +Node.js applications can update parameter and event definitions and write data to streams using RESTful APIs. Quix supports WebSockets for clients that want to receive telemetry data and parameters/events updates in real-time. Node.js clients must authenticate with Quix using [personal access tokens](../how-to/personal-access-token-pat.md). diff --git a/docs/platform/how-to/webapps/write.md b/docs/platform/how-to/webapps/write.md index 922f8b34..ce95e130 100644 --- a/docs/platform/how-to/webapps/write.md +++ b/docs/platform/how-to/webapps/write.md @@ -51,13 +51,13 @@ req.end(); Upon completing the request successfully, you will receive the stream ID in the response body. You are going to need this stream id when you are writing data to the stream. -In the request data, `Location` is also an optional, but an important property. Location allows you to organize your streams under directories in the Quix data store. +In the request data, `Location` is also an optional, but an important property. Location enables you to organize your streams under directories in the Quix data store. When you are creating the stream, you can add optional metadata about the stream to the stream definition like `Property1` and `Property2` in the preceding example. Field `Parents` is also optional. If the current stream is derived from one or more streams (e.g. by transforming data from one stream using an analytics model), you can reference the original streams using this field. -`TimeOfRecording` is an optional field that allows you to specify the actual time the data was recorded. This field is useful if you are streaming data that was recorded in the past. +`TimeOfRecording` is an optional field that enables you to specify the actual time the data was recorded. This field is useful if you are streaming data that was recorded in the past. ## Writing parameter data to a stream @@ -107,7 +107,7 @@ req.end(); In the preceding example, `data` has two different parameter types, numeric and strings. If your data only contains numeric data, you do not need to include the `StringValues` property. In the case of binary values, the items in the array must be a base64 encoded string. -`TagValues` is another optional field in the data request that allows you to add context to data points by means of tagging them. Index of the `Timestamps` array is used when matching the parameter data values as well as tag values. Therefore, the order of the arrays is important. +`TagValues` is another optional field in the data request that enables you to add context to data points by means of tagging them. Index of the `Timestamps` array is used when matching the parameter data values as well as tag values. Therefore, the order of the arrays is important. ## Defining parameters @@ -147,7 +147,7 @@ req.write(data); req.end(); ``` -In the preceding request, the `Id` must match the parameter ID you set when writing data to the stream. `Name` allows you to set a more readable name for the parameter. You can also add a description, minimum and maximum values, unit of measurement to your parameter. `Location` allows you to organize/group your parameters in a hierarchical manner like with the streams. If you have a custom parameter definition that is not covered by the primary fields of the request, you can use `CustomProperties` field to add your custom definition as a string. +In the preceding request, the `Id` must match the parameter ID you set when writing data to the stream. `Name` enables you to set a more readable name for the parameter. You can also add a description, minimum and maximum values, unit of measurement to your parameter. `Location` enables you to organize/group your parameters in a hierarchical manner like with the streams. If you have a custom parameter definition that is not covered by the primary fields of the request, you can use `CustomProperties` field to add your custom definition as a string. ## Writing event data to a stream @@ -239,7 +239,7 @@ req.write(data); req.end(); ``` -In the preceding request, the `Id` must match the event id you set when writing events to the stream. `Name` allows you to set a more readable name for the event. `Location` allows you to organize/group your events in a hierarchy like with the parameters. If you have a custom event definition that is not covered by the primary fields of the request, you can use `CustomProperties` field to add your custom definition as a string. You can also set an optional event `Level`. Accepted event levels are Trace, Debug, Information, Warning, Error and Critical. Event level defaults to Information if not specified. +In the preceding request, the `Id` must match the event id you set when writing events to the stream. `Name` enables you to set a more readable name for the event. `Location` enables you to organize/group your events in a hierarchy like with the parameters. If you have a custom event definition that is not covered by the primary fields of the request, you can use `CustomProperties` field to add your custom definition as a string. You can also set an optional event `Level`. Accepted event levels are Trace, Debug, Information, Warning, Error and Critical. Event level defaults to Information if not specified. ## Closing a stream diff --git a/docs/platform/images/how-to/get-environment-id/get-environment-id-settings.png b/docs/platform/images/how-to/get-environment-id/get-environment-id-settings.png new file mode 100644 index 00000000..33adc1e3 Binary files /dev/null and b/docs/platform/images/how-to/get-environment-id/get-environment-id-settings.png differ diff --git a/docs/platform/ingest-data.md b/docs/platform/ingest-data.md index 3a73e78b..2e5a9f66 100644 --- a/docs/platform/ingest-data.md +++ b/docs/platform/ingest-data.md @@ -140,8 +140,8 @@ See also [How to deploy a public service](../platform/how-to/deploy-public-page. Quix provides two APIs with an HTTP API interface: -1. [Writer API](../apis/streaming-writer-api/intro.md) -2. [Reader API](../apis/streaming-reader-api/intro.md) +1. [Writer API](../apis/streaming-writer-api/index.md) +2. [Reader API](../apis/streaming-reader-api/index.md) The Writer API is used to write data into the Quix Platform, that is, it is used by publishers. The Reader API is used to read data from the Quix Platform, and is therefore used by consumers. These are used typically by external services such as web browser client code, or perhaps IoT devices. The Reader and Writer APIs also provide a WebSockets interface, which is described in the [next section](#websockets). @@ -175,7 +175,7 @@ As you can see there are other options such as generating Curl code that can be The code samples generated are meant to provide you with a starting point from which you can build your own solutions. They provide a convenient way to see how the API works. -Further information can be found in the [Writer API](../apis/streaming-writer-api/intro.md) and [Reader API](../apis/streaming-reader-api/intro.md) documentation. +Further information can be found in the [Writer API](../apis/streaming-writer-api/index.md) and [Reader API](../apis/streaming-reader-api/index.md) documentation. ## WebSockets @@ -348,7 +348,7 @@ Code that could read mouse cursor position from a Quix stream is as follows: This code uses the Reader API to read data from a Quix stream. -The Quix documentation explains how to obtain your [Quix environment ID](../platform/how-to/get-environment-id.md), [PAT token](../apis/streaming-reader-api/authenticate.md) for authentication, and also how to [set up SignalR](../apis/streaming-reader-api/signalr.md). +The Quix documentation explains how to obtain your [Quix environment ID](../platform/how-to/get-environment-id.md), [PAT token](../platform/how-to/personal-access-token-pat.md) for authentication, and also how to [set up SignalR](../apis/streaming-reader-api/signalr.md). ## Push data using Quix Streams @@ -480,4 +480,4 @@ If you want some example code you can use as a starting point for connecting you Low-frequency data from REST APIs can be [polled](#polling) from Quix using a library such as `requests`. -Quix also provides the [streaming writer](../apis/streaming-writer-api/intro.md) and [streaming reader](../apis/streaming-reader-api/intro.md) APIs with both HTTP and WebSockets interfaces. If a continous connection is not required you can use the HTTP interface. Faster data from web servers, browser clients, and IoT devices can interface [using ebSockets](#websockets), where a continuous connection is required. +Quix also provides the [streaming writer](../apis/streaming-writer-api/index.md) and [streaming reader](../apis/streaming-reader-api/index.md) APIs with both HTTP and WebSockets interfaces. If a continous connection is not required you can use the HTTP interface. Faster data from web servers, browser clients, and IoT devices can interface [using ebSockets](#websockets), where a continuous connection is required. diff --git a/docs/platform/samples/samples.md b/docs/platform/samples/samples.md index b4b74e97..f19dd6ac 100644 --- a/docs/platform/samples/samples.md +++ b/docs/platform/samples/samples.md @@ -4,7 +4,7 @@ The Quix Portal includes Quix Code Samples, a collection of templates and sample ![Code Samples](../samples/code-samples.png) -Quix allows you to explore the Code Samples and save them as a new application and immediately run or deploy them. +Quix enables you to explore the Code Samples and save them as a new application and immediately run or deploy them. If you don't have a Quix account yet, go [sign-up to Quix](https://portal.platform.quix.ai/self-sign-up?xlink=docs){target=_blank} and create one. diff --git a/docs/platform/security/security.md b/docs/platform/security/security.md index f317a52b..c24dc25f 100644 --- a/docs/platform/security/security.md +++ b/docs/platform/security/security.md @@ -10,7 +10,7 @@ This document outlines how Quix helps customers configure, deploy and use the cl ## Authentication -Securing your information starts with identity controls, no matter where your users are located. Quix allows you to manage users, streamline authentication using your identity provider, and assign roles. We give you the solutions to ensure that only the right people can access your company's information in Quix. +Securing your information starts with identity controls, no matter where your users are located. Quix enables you to manage users, streamline authentication using your identity provider, and assign roles. We give you the solutions to ensure that only the right people can access your company's information in Quix. OAuth is the protocol Quix uses when you auth against our platform using Google or your preferred Identity provider. Customers are responsible for integrating and managing their identity provider (for single sign-on and provisioning) as well as assigning roles in Quix. @@ -52,7 +52,7 @@ To give you even further protection and control, we architected Quix on independ Environments at Quix are hermetically sealed with no reused components between them. Development and Production environments are distinct entities with no cross-talk. -The separation of these concerns allows us to deliver a Quix platform experience in a way that minimizes the chance of errors and mistakes and is a well-supported industry standard of software delivery. +The separation of these concerns enables us to deliver a Quix platform experience in a way that minimizes the chance of errors and mistakes and is a well-supported industry standard of software delivery. In case you choose to host Quix on your platform, we recommend that you follow the same practices. diff --git a/docs/platform/tutorials/data-science/3-data.md b/docs/platform/tutorials/data-science/3-data.md index 49b8e66b..7f58de23 100644 --- a/docs/platform/tutorials/data-science/3-data.md +++ b/docs/platform/tutorials/data-science/3-data.md @@ -34,7 +34,7 @@ Now you know how to observe data arriving into your topics. You can also explore ## Historical data -In order to train a machine learning model on historical data, the live real-time data being ingested needs to be stored. However, topics are real time and therefore not designed for data storage. To solve this, Quix allows you to store the data going through a topic to an efficient real-time database if you need it. +In order to train a machine learning model on historical data, the live real-time data being ingested needs to be stored. However, topics are real time and therefore not designed for data storage. To solve this, Quix enables you to store the data going through a topic to an efficient real-time database if you need it. Enable persistence on your topics: diff --git a/docs/platform/tutorials/data-science/4-train.md b/docs/platform/tutorials/data-science/4-train.md index 12d3466b..6bf88c07 100644 --- a/docs/platform/tutorials/data-science/4-train.md +++ b/docs/platform/tutorials/data-science/4-train.md @@ -6,7 +6,7 @@ Follow along and learn how to retrieve historical data from your topics, so you ## Limited data set -You've already read about the limitations of the free Visual Crossing API. Namely, that it only allows requests for new data 1000 times per day and so the Quix Code Sample only requests data very 2 minutes, therefore at this point in the tutorial you may have a limited data set. +You've already read about the limitations of the free Visual Crossing API. Namely, that it only enables requests for new data 1000 times per day and so the Quix Code Sample only requests data very 2 minutes, therefore at this point in the tutorial you may have a limited data set. Continue following the tutorial to see how to access the accumulated historical data, however, after a few hours you will have more data to examine at which time you can repeat the steps again. diff --git a/docs/platform/tutorials/data-stream-processing/data-stream-processing.md b/docs/platform/tutorials/data-stream-processing/data-stream-processing.md index d7b6d853..fc708f47 100644 --- a/docs/platform/tutorials/data-stream-processing/data-stream-processing.md +++ b/docs/platform/tutorials/data-stream-processing/data-stream-processing.md @@ -225,7 +225,7 @@ You should be familiar with the process by now. Look for those lines in the `create-page.js` file and explore what they do. - For more about WebSockets see [this page](../../../apis/streaming-reader-api/intro.md). + For more about WebSockets see [this page](../../../apis/streaming-reader-api/index.md). ## Fun diff --git a/docs/platform/tutorials/image-processing/get-project.md b/docs/platform/tutorials/image-processing/get-project.md index 4617e633..6062f7c6 100644 --- a/docs/platform/tutorials/image-processing/get-project.md +++ b/docs/platform/tutorials/image-processing/get-project.md @@ -23,7 +23,7 @@ The key ideas on this page: ## Fork the project repository -Quix provides the image processing template project as a [public GitHub repository](https://github.com/quixio/computer-vision-demo){target="_blank"}. If you want to use this template as a starting point for your own project, then the best way to accomplish this is to fork the project. Using fork allows you to create a complete copy of the project, but also benefit from future bug fixes and improvements by using the upstream changes. +Quix provides the image processing template project as a [public GitHub repository](https://github.com/quixio/computer-vision-demo){target="_blank"}. If you want to use this template as a starting point for your own project, then the best way to accomplish this is to fork the project. Using fork enables you to create a complete copy of the project, but also benefit from future bug fixes and improvements by using the upstream changes. To fork the repository: diff --git a/docs/platform/tutorials/image-processing/index.md b/docs/platform/tutorials/image-processing/index.md index 288c168b..3ef26237 100644 --- a/docs/platform/tutorials/image-processing/index.md +++ b/docs/platform/tutorials/image-processing/index.md @@ -32,7 +32,7 @@ Some of the technologies used by this template project are listed here. **Backend:** -* [Apache Kafka](https://kafka.apache.org/){target=_blank} +* [Confluent Cloud](https://www.confluent.io/lp/confluent-cloud/){target=_blank} * [Quix Streams](https://github.com/quixio/quix-streams){target=_blank} * [Flask](https://flask.palletsprojects.com/en/2.3.x/#){target=_blank} * [pandas](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html){target=_blank} @@ -133,7 +133,7 @@ There are several *main* stages in the pipeline: 4. *Stream merge* - merges the separate data streams (one for each camera) back into one, prior to sending to the UI. -5. *Web UI* - a UI that displays: frames with the objects that have been identified, and a map with a count of objects at each camera's location. The web UI is a web client app that uses the [Quix Streaming Reader API](../../../apis/streaming-reader-api/intro.md), to read data from a Quix topic. +5. *Web UI* - a UI that displays: frames with the objects that have been identified, and a map with a count of objects at each camera's location. The web UI is a web client app that uses the [Quix Streaming Reader API](../../../apis/streaming-reader-api/index.md), to read data from a Quix topic. There are also some additional services in the pipeline: diff --git a/docs/platform/tutorials/image-processing/summary.md b/docs/platform/tutorials/image-processing/summary.md index e1e48eb1..09216937 100644 --- a/docs/platform/tutorials/image-processing/summary.md +++ b/docs/platform/tutorials/image-processing/summary.md @@ -1,6 +1,6 @@ # Summary -In this tutorial you have learned that it is possible to quickly fork a complete Quix project and get it up and running in your Quix account very quickly. This allows you to start your own project by using one of our templates. You can then modify our code, keeping your project in a public or private Git repository as required. Alternatively, you can build your own custom pipeline from a mix of our code samples, and your own custom sources, transforms, and destinations. +In this tutorial you have learned that it is possible to quickly fork a complete Quix project and get it up and running in your Quix account very quickly. This enables you to start your own project by using one of our templates. You can then modify our code, keeping your project in a public or private Git repository as required. Alternatively, you can build your own custom pipeline from a mix of our code samples, and your own custom sources, transforms, and destinations. In addition, you have see how in the Quix portal you can: diff --git a/docs/platform/tutorials/image-processing/web-ui.md b/docs/platform/tutorials/image-processing/web-ui.md index 83134693..c56427ab 100644 --- a/docs/platform/tutorials/image-processing/web-ui.md +++ b/docs/platform/tutorials/image-processing/web-ui.md @@ -23,7 +23,7 @@ The key ideas on this page: The key thing this service does is provide a UI that enables you to see vehicle data in real time, displayed on a Google map. -The UI is an Angular web client written using Typescript. The most important thing to understand is how this service obtains data from the Quix pipeline. This is done through use of the [Quix Streaming Reader API](../../../apis/streaming-reader-api/intro.md). +The UI is an Angular web client written using Typescript. The most important thing to understand is how this service obtains data from the Quix pipeline. This is done through use of the [Quix Streaming Reader API](../../../apis/streaming-reader-api/index.md). The Streaming Reader API has both an HTTP and WebSockets interface you can use to interface with a Quix topic. This web client uses the WebSockets interface. This enables data to be streamed from the Quix topic into the web client with good performance. This is a more efficient method than using the request-response method of HTTP. @@ -62,7 +62,7 @@ So, simplifying, after connection to the Quix topic, on a `ParameterDataReceived !!! note - A web client can also write data into a Quix topic using the [Quix Streaming Writer API](../../../apis/streaming-writer-api/intro.md), but in this app you only consume (read) data. + A web client can also write data into a Quix topic using the [Quix Streaming Writer API](../../../apis/streaming-writer-api/index.md), but in this app you only consume (read) data. The data read from the topic is as follows: @@ -112,7 +112,7 @@ The interesting thing here is that the detected object image to be displayed by You learned how to explore the code for a service in previous parts of this tutorial. The web UI is a fairly standard web client using Angular. -For more details on using the Quix Streaming Reader API see the [API documentation](../../../apis/streaming-reader-api/intro.md). +For more details on using the Quix Streaming Reader API see the [API documentation](../../../apis/streaming-reader-api/index.md). ## 👩‍🔬 Lab - Explore the UI @@ -130,7 +130,7 @@ Have fun! For more information refer to: -* [Quix Streaming Reader API](../../../apis/streaming-reader-api/intro.md) - read about the API used by clients external to Quix to read data from a Quix topic. +* [Quix Streaming Reader API](../../../apis/streaming-reader-api/index.md) - read about the API used by clients external to Quix to read data from a Quix topic. ## 🏃‍♀️ Next step diff --git a/docs/platform/tutorials/sentiment-analysis/get-project.md b/docs/platform/tutorials/sentiment-analysis/get-project.md index fcec9525..77d054b7 100644 --- a/docs/platform/tutorials/sentiment-analysis/get-project.md +++ b/docs/platform/tutorials/sentiment-analysis/get-project.md @@ -23,7 +23,7 @@ The key ideas on this page: ## Fork the project repository -Quix provides the image processing template project as a [public GitHub repository](https://github.com/quixio/chat-demo-app){target="_blank"}. If you want to use this template as a starting point for your own project, then the best way to accomplish this is to fork the project. Using fork allows you to create a complete copy of the project, but also benefit from future bug fixes and improvements by using the upstream changes. +Quix provides the image processing template project as a [public GitHub repository](https://github.com/quixio/chat-demo-app){target="_blank"}. If you want to use this template as a starting point for your own project, then the best way to accomplish this is to fork the project. Using fork enables you to create a complete copy of the project, but also benefit from future bug fixes and improvements by using the upstream changes. To fork the repository: diff --git a/docs/platform/tutorials/sentiment-analysis/index.md b/docs/platform/tutorials/sentiment-analysis/index.md index 5af82cb5..2017f23e 100644 --- a/docs/platform/tutorials/sentiment-analysis/index.md +++ b/docs/platform/tutorials/sentiment-analysis/index.md @@ -36,7 +36,7 @@ Some of the technologies used by this template project are listed here. **Backend:** -* [Apache Kafka](https://kafka.apache.org/){target=_blank} +* [Redpanda cloud](https://redpanda.com/redpanda-cloud){target=_blank} * [Quix Streams](https://github.com/quixio/quix-streams){target=_blank} * [Flask](https://flask.palletsprojects.com/en/2.3.x/#){target=_blank} * [pandas](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html){target=_blank} diff --git a/docs/platform/tutorials/sentiment-analysis/summary.md b/docs/platform/tutorials/sentiment-analysis/summary.md index 5145901d..a80f9b89 100644 --- a/docs/platform/tutorials/sentiment-analysis/summary.md +++ b/docs/platform/tutorials/sentiment-analysis/summary.md @@ -4,7 +4,7 @@ In this tutorial you've learned: * How to fork a GitHub repository and then integrate it with Quix * Examined the code for several services in the pipeline -* Learned that web apps can read and write to Quix topics using the [Quix Streaming APIs](../../../apis/index.md) +* Learned that web apps can read and write to Quix topics using the [Quix Streaming APIs](../../../apis/intro.md) * Used the message view in the Quix UI to examine messages flowing on topics. * Created a customization to the UI on a feature environment (branch) and then seen how to merge that to develop diff --git a/docs/platform/tutorials/sentiment-analysis/ui-service.md b/docs/platform/tutorials/sentiment-analysis/ui-service.md index 4cbc1a18..7d552d1f 100644 --- a/docs/platform/tutorials/sentiment-analysis/ui-service.md +++ b/docs/platform/tutorials/sentiment-analysis/ui-service.md @@ -30,8 +30,8 @@ The most important thing to understand is how this service reads and writes data This is done through use of two APIs: -* [Quix Streaming Reader API](../../../apis/streaming-reader-api/intro.md) -* [Quix Streaming Writer API](../../../apis/streaming-writer-api/intro.md) +* [Quix Streaming Reader API](../../../apis/streaming-reader-api/index.md) +* [Quix Streaming Writer API](../../../apis/streaming-writer-api/index.md) The Streaming Writer is used to write both published and draft messages to the sentiment analysis service. Note the UI provides sentiment analysis of messages as they are being typed, that is, in the draft state, as they have not yet been sent to the chat room. @@ -71,8 +71,8 @@ The Streaming Writer API is [used in a similar way](../../../apis/streaming-writ For more information refer to: -* [Quix Streaming Reader API](../../../apis/streaming-reader-api/intro.md) - read about the API used by clients external to Quix to read data from a Quix topic. -* [Quix Streaming Writer API](../../../apis/streaming-writer-api/intro.md) - read about the API used by clients external to Quix to write data to a Quix topic. +* [Quix Streaming Reader API](../../../apis/streaming-reader-api/index.md) - read about the API used by clients external to Quix to read data from a Quix topic. +* [Quix Streaming Writer API](../../../apis/streaming-writer-api/index.md) - read about the API used by clients external to Quix to write data to a Quix topic. ## 🏃‍♀️ Next step diff --git a/docs/platform/tutorials/slack-alerting/slack-alerting.md b/docs/platform/tutorials/slack-alerting/slack-alerting.md index ac9e4b2e..0d82888e 100644 --- a/docs/platform/tutorials/slack-alerting/slack-alerting.md +++ b/docs/platform/tutorials/slack-alerting/slack-alerting.md @@ -269,6 +269,6 @@ Follow these steps: There are many ways you can use this code, try enhancing it so it only alerts you about each location once, or once every 5 minutes. -Using Quix, coupled with something like Slack, allows for automatic real-time alerting. Quix allows you to react in real-time to events or anomalies found either in raw data or generated by ML models. +Using Quix, coupled with something like Slack, enables for automatic real-time alerting. Quix enables you to react in real time to events or anomalies found either in raw data or generated by ML models. If you need any help, please sign up to the [Quix community forum](https://forum.quix.io/){target=_blank}. \ No newline at end of file diff --git a/docs/platform/tutorials/train-and-deploy-ml/create-data.md b/docs/platform/tutorials/train-and-deploy-ml/create-data.md index fc6f67b8..b1129a77 100644 --- a/docs/platform/tutorials/train-and-deploy-ml/create-data.md +++ b/docs/platform/tutorials/train-and-deploy-ml/create-data.md @@ -38,6 +38,6 @@ Now generate the actual data for use later in the tutorial by completing the fol Once this service is deployed it will run as a [job](../../glossary.md#job) and generate real-time data to the `f1-data`, and this will be persisted. -This data is retrieved later in this tutorial using Python code that uses the [Query API](../../../apis/query-api/intro.md), generated for you by Quix. +This data is retrieved later in this tutorial using Python code that uses the [Query API](../../../apis/query-api/index.md), generated for you by Quix. [Import data into Jupyter Notebook :material-arrow-right-circle:{ align=right }](./import-data.md) diff --git a/docs/platform/tutorials/train-and-deploy-ml/import-data.md b/docs/platform/tutorials/train-and-deploy-ml/import-data.md index 9f4f69f5..c748abfe 100644 --- a/docs/platform/tutorials/train-and-deploy-ml/import-data.md +++ b/docs/platform/tutorials/train-and-deploy-ml/import-data.md @@ -1,6 +1,6 @@ # Import data into Jupyter Notebook -From a Jupyter Notebook, you retrieve the data that was generated in Quix in the [previous part](./create-data.md), and which was persisted into the [Quix data store](../../../apis/query-api/intro.md). +From a Jupyter Notebook, you retrieve the data that was generated in Quix in the [previous part](./create-data.md), and which was persisted into the [Quix data store](../../../apis/query-api/index.md). ## Run Jupyter Notebook diff --git a/docs/platform/what-is-quix.md b/docs/platform/what-is-quix.md index abbd9c3e..47f79864 100644 --- a/docs/platform/what-is-quix.md +++ b/docs/platform/what-is-quix.md @@ -124,10 +124,10 @@ Quix provides numerous standard [connectors](../platform/connectors/index.md) fo Quix provides several APIs to help you work with streaming data. These include: -* [**Stream Writer API**](../apis/streaming-writer-api/intro.md): enables you to send any data to a Kafka topic in Quix using HTTP. This API handles encryption, serialization, and conversion to the Quix Streams format, ensuring efficiency and performance of down-stream processing regardless of the data source. -* [**Stream Reader API**](../apis/streaming-reader-api/intro.md): enables you to push live data from a Quix topic to your application, ensuring low latency by avoiding any disk operations. -* [**Query API**](../apis/query-api/intro.md): enables you to query persisted data streams. This is provided primarily for testing purposes. -* [**Portal API**](../apis/portal-api.md): enables you to automate Quix Portal tasks such as creating environments, topics, and deployments. +* [**Stream Writer API**](../apis/streaming-writer-api/index.md): enables you to send any data to a Kafka topic in Quix using HTTP. This API handles encryption, serialization, and conversion to the Quix Streams format, ensuring efficiency and performance of down-stream processing regardless of the data source. +* [**Stream Reader API**](../apis/streaming-reader-api/index.md): enables you to push live data from a Quix topic to your application, ensuring low latency by avoiding any disk operations. +* [**Query API**](../apis/query-api/index.md): enables you to query persisted data streams. This is provided primarily for testing purposes. +* [**Portal API**](../apis/portal-api/index.md): enables you to automate Quix Portal tasks such as creating environments, topics, and deployments. ### Quix Streams diff --git a/mkdocs.yml b/mkdocs.yml index 5db275bf..4f85f423 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -103,12 +103,25 @@ nav: - 'MLOps': 'platform/MLOps.md' - 'Client Library': '!import https://github.com/quixio/quix-streams?branch=main' - API: - - 'Index': 'apis/index.md' - - 'Query API': - - 'Introduction': 'apis/query-api/intro.md' - - 'Authenticate': 'apis/query-api/authenticate.md' - - 'Getting Swagger URL': 'apis/query-api/get-swagger.md' - - 'Forming a request': 'apis/query-api/request.md' + - 'Intro': 'apis/intro.md' + - 'Prerequisites': 'apis/prerequisites.md' + - 'API References': 'apis/api-references.md' + - 'HTTP requests': 'apis/http-requests.md' + - 'Set up SignalR': 'apis/signalr.md' + - 'Streaming Writer API': + - 'apis/streaming-writer-api/index.md' + - 'Create a new Stream': 'apis/streaming-writer-api/create-stream.md' + - 'Add Stream metadata': 'apis/streaming-writer-api/stream-metadata.md' + - 'Send Parameter data': 'apis/streaming-writer-api/send-data.md' + - 'Send an Event': 'apis/streaming-writer-api/send-event.md' + - 'Streaming Reader API': + - 'apis/streaming-reader-api/index.md' + - 'Reading data': 'apis/streaming-reader-api/reading-data.md' + - 'Subscription and events': 'apis/streaming-reader-api/subscriptions.md' + - 'Portal API': + - 'apis/portal-api/index.md' + - 'Query API': + - 'apis/query-api/index.md' - 'Paged streams': 'apis/query-api/streams-paged.md' - 'Filtered streams': 'apis/query-api/streams-filtered.md' - 'Streams with models': 'apis/query-api/streams-models.md' @@ -116,23 +129,6 @@ nav: - 'Aggregate data by time': 'apis/query-api/aggregate-time.md' - 'Aggregate data by tags': 'apis/query-api/aggregate-tags.md' - 'Tag filtering': 'apis/query-api/filter-tags.md' - - 'Streaming Writer API': - - 'Introduction': 'apis/streaming-writer-api/intro.md' - - 'Authenticate': 'apis/streaming-writer-api/authenticate.md' - - 'Getting Swagger URL': 'apis/streaming-writer-api/get-swagger.md' - - 'Forming a request': 'apis/streaming-writer-api/request.md' - - 'Set up SignalR': 'apis/streaming-writer-api/signalr.md' - - 'Create a new Stream': 'apis/streaming-writer-api/create-stream.md' - - 'Add Stream metadata': 'apis/streaming-writer-api/stream-metadata.md' - - 'Send Parameter data': 'apis/streaming-writer-api/send-data.md' - - 'Send an Event': 'apis/streaming-writer-api/send-event.md' - - 'Streaming Reader API': - - 'Introduction': 'apis/streaming-reader-api/intro.md' - - 'Authenticate': 'apis/streaming-reader-api/authenticate.md' - - 'Set up SignalR': 'apis/streaming-reader-api/signalr.md' - - 'Reading data': 'apis/streaming-reader-api/reading-data.md' - - 'Subscription & Event reference': 'apis/streaming-reader-api/subscriptions.md' - - 'Portal API': 'apis/portal-api.md' plugins: - multirepo: @@ -172,8 +168,13 @@ plugins: 'platform/tutorials/quick-start/quick-start.md': 'platform/quickstart.md' 'platform/how-to/use-sdk-token.md': 'platform/how-to/streaming-token.md' 'platform/how-to/connect-to-quix.md': 'platform/ingest-data.md' - 'apis/data-catalogue-api/intro.md': 'apis/query-api/intro.md' 'platform/tutorials/image-processing/connect-video-tfl.md': 'platform/tutorials/image-processing/tfl-camera-feed.md' + 'apis/data-catalogue-api/intro.md': 'apis/query-api/index.md' + 'apis/streaming-reader-api/intro.md': 'apis/streaming-reader-api/index.md' + 'apis/streaming-writer-api/intro.md': 'apis/streaming-writer-api/index.md' + 'apis/query-api/intro.md': 'apis/query-api/index.md' + 'apis/portal-api.md': 'apis/portal-api/index.md' + 'apis/index.md': 'apis/intro.md' theme: