From 697ddecbf841d986c7eb79f8d3fa1aa1659f0088 Mon Sep 17 00:00:00 2001 From: Paul Wozniczka <25128922+pwoznic@users.noreply.github.com> Date: Wed, 24 Jan 2024 11:30:38 -0600 Subject: [PATCH 1/6] Update labels and organization of endpoints --- www/docs/api-reference/admin-apis/admin.md | 4 +- www/sidebars.js | 234 +++++++++++---------- 2 files changed, 120 insertions(+), 118 deletions(-) diff --git a/www/docs/api-reference/admin-apis/admin.md b/www/docs/api-reference/admin-apis/admin.md index 6546e9d04..63f84cd2c 100644 --- a/www/docs/api-reference/admin-apis/admin.md +++ b/www/docs/api-reference/admin-apis/admin.md @@ -1,7 +1,7 @@ --- id: admin -title: Corpus Administration APIs -sidebar_label: Corpus Administration APIs +title: Corpus Administration +sidebar_label: Corpus Administration --- import Tabs from '@theme/Tabs'; diff --git a/www/sidebars.js b/www/sidebars.js index a73a4ac7e..847399c30 100644 --- a/www/sidebars.js +++ b/www/sidebars.js @@ -165,7 +165,118 @@ module.exports = { 'api-reference/api-overview', 'api-reference/protobuf-definitions', 'api-reference/rest', - { + { + type: `category`, + label: `Account Admin APIs`, + items: [ + 'api-reference/admin-apis/compute-account-size' + ] + }, + { + type: `category`, + label: `Access Admin APIs`, + items: [ + { + type: 'category', + label: 'User Admin APIs', + items: [ + 'api-reference/admin-apis/manage-users/list-users', + 'api-reference/admin-apis/manage-users/manage-user', + ] + }, + { + type: 'category', + label: 'API Key Admin APIs', + items: [ + 'api-reference/api-keys/create-api-key', + 'api-reference/api-keys/delete-api-key', + 'api-reference/api-keys/list-api-keys', + 'api-reference/api-keys/enable-api-key', + ] + }, + ] + }, + { + type: 'category', + label: 'Corpus Admin APIs', + items: [ + 'api-reference/admin-apis/admin', + { + type: 'category', + label: 'Create Corpus', + items: [ + 'api-reference/admin-apis/create-corpus', + { + type: 'category', + label: 'Create Corpus REST Examples', + items: [ + 'getting-started-samples/RestCreateCorpus.java', + 'getting-started-samples/create_corpus.js', + 'getting-started-samples/createCorpus.php', + 'getting-started-samples/rest_create_corpus.py' + ] + } + ] + }, + { + type: 'category', + label: 'Delete Corpus', + items: [ + 'api-reference/admin-apis/delete-corpus', + { + type: 'category', + label: 'Delete Corpus REST Examples', + items: [ + 'getting-started-samples/RestDeleteCorpus.cs', + 'getting-started-samples/delete_corpus.js', + 'getting-started-samples/deleteCorpus.php', + 'getting-started-samples/rest_delete_corpus.py' + ] + } + ] + }, + { + type: 'category', + label: 'Reset Corpus', + items: [ + 'api-reference/admin-apis/reset-corpus', + { + type: 'category', + label: 'Reset Corpus REST Examples', + items: [ + 'getting-started-samples/RestResetCorpus.cs', + 'getting-started-samples/reset_corpus.js', + 'getting-started-samples/resetCorpus.php', + 'getting-started-samples/rest_reset_corpus.py' + ] + } + ] + }, + 'api-reference/admin-apis/corpus/update-corpus-enablement', + 'api-reference/admin-apis/corpus/read-corpus', + 'api-reference/admin-apis/corpus/compute-corpus-size', + ] + }, + { + type: 'category', + label: 'Document Admin APIs', + items: [ + 'api-reference/admin-apis/corpus/list-documents', + 'api-reference/indexing-apis/deleting-documents', + { + type: 'category', + label: 'Delete Document REST Examples', + items: [ + 'getting-started-samples/RestDeleteDocument.cs', + 'getting-started-samples/RestDeleteDocument.java', + 'getting-started-samples/delete_document.js', + 'getting-started-samples/deleteDocument.php', + 'getting-started-samples/rest_delete_document.py', + ] + }, + ] + }, + { type: 'category', label: 'Indexing APIs', items: [ @@ -176,7 +287,7 @@ module.exports = { 'api-reference/indexing-apis/indexing', { type: 'category', - label: 'REST Examples', + label: 'Standard Indexing REST Examples', items: [ 'getting-started-samples/RestIndexData.cs', 'getting-started-samples/RestIndex.java', @@ -203,7 +314,7 @@ module.exports = { 'api-reference/indexing-apis/file-upload/file-upload-filetypes', { type: 'category', - label: 'REST Examples', + label: 'File Upload REST Examples', items: [ 'getting-started-samples/RestUploadFile.java', 'getting-started-samples/upload_file.js', @@ -215,36 +326,18 @@ module.exports = { }, ], }, - { - type: 'category', - label: 'Delete Documents API', - items: [ - 'api-reference/indexing-apis/deleting-documents', - { - type: 'category', - label: 'REST Examples', - items: [ - 'getting-started-samples/RestDeleteDocument.cs', - 'getting-started-samples/RestDeleteDocument.java', - 'getting-started-samples/delete_document.js', - 'getting-started-samples/deleteDocument.php', - 'getting-started-samples/rest_delete_document.py', - ] - }, - ] - }, { type: 'category', - label: 'Search APIs', + label: 'Query APIs', items: [ { type: 'category', - label: 'Standard Search API', + label: 'Standard Query API', items: [ 'api-reference/search-apis/search', { type: 'category', - label: 'REST Examples', + label: 'Standard Query REST Examples', items: [ 'getting-started-samples/RestQueryData.cs', 'getting-started-samples/RestQuery.java', @@ -268,98 +361,7 @@ module.exports = { }, ], }, - { - type: 'category', - label: 'Admin APIs', - items: [ - 'api-reference/admin-apis/compute-account-size', - 'api-reference/admin-apis/manage-users/list-users', - 'api-reference/admin-apis/manage-users/manage-user', - 'api-reference/admin-apis/admin', - { - type: 'category', - label: 'Create Corpus', - items: [ - 'api-reference/admin-apis/create-corpus', - { - type: 'category', - label: 'REST Examples', - items: [ - 'getting-started-samples/RestCreateCorpus.java', - 'getting-started-samples/create_corpus.js', - 'getting-started-samples/createCorpus.php', - 'getting-started-samples/rest_create_corpus.py' - ] - } - ] - }, - { - type: 'category', - label: 'Delete Corpus', - items: [ - 'api-reference/admin-apis/delete-corpus', - { - type: 'category', - label: 'REST Examples', - items: [ - 'getting-started-samples/RestDeleteCorpus.cs', - 'getting-started-samples/delete_corpus.js', - 'getting-started-samples/deleteCorpus.php', - 'getting-started-samples/rest_delete_corpus.py' - ] - } - ] - }, - { - type: 'category', - label: 'Reset Corpus', - items: [ - 'api-reference/admin-apis/reset-corpus', - { - type: 'category', - label: 'REST Examples', - items: [ - 'getting-started-samples/RestResetCorpus.cs', - 'getting-started-samples/reset_corpus.js', - 'getting-started-samples/resetCorpus.php', - 'getting-started-samples/rest_reset_corpus.py' - ] - } - ] - }, - { - type: 'doc', - id: 'api-reference/admin-apis/corpus/list-documents', - label: "List Documents API Definition", - }, - { - type: 'doc', - id: 'api-reference/admin-apis/corpus/compute-corpus-size', - label: "Compute Corpus Size API Definition", - }, - { - type: 'doc', - id: 'api-reference/admin-apis/corpus/read-corpus', - label: "Read Corpus API Definition", - }, - { - type: 'doc', - id: 'api-reference/admin-apis/corpus/update-corpus-enablement', - label: "Update Corpus Enablement API Definition", - }, - { - type: 'category', - label: 'API Key Management APIs', - items: [ - 'api-reference/api-keys/create-api-key', - 'api-reference/api-keys/delete-api-key', - 'api-reference/api-keys/list-api-keys', - 'api-reference/api-keys/enable-api-key', - ] - }, - ], - }, - ], + ], }, { type: 'category', From 8f7fd015bba5d19fe5a47ee2663511be8fa11544 Mon Sep 17 00:00:00 2001 From: Paul Wozniczka <25128922+pwoznic@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:10:42 -0600 Subject: [PATCH 2/6] Update API Reference topics for more consistency Updated additional topics to have a similar look and feel, along with label updates and other misc changes --- www/docs/api-reference/admin-apis/admin.md | 11 +- .../admin-apis/compute-account-size.md | 4 +- .../admin-apis/corpus/compute-corpus-size.md | 4 +- .../admin-apis/corpus/list-documents.md | 8 +- .../admin-apis/corpus/read-corpus.md | 6 +- .../corpus/update-corpus-enablement.md | 4 +- .../api-reference/admin-apis/create-corpus.md | 176 ++++++++---------- .../api-reference/admin-apis/delete-corpus.md | 52 ++++-- .../admin-apis/manage-users/list-users.md | 87 +++++++-- .../admin-apis/manage-users/manage-user.md | 42 ++--- .../api-reference/admin-apis/reset-corpus.md | 45 +++-- .../api-reference/api-keys/create-api-key.md | 28 ++- .../api-reference/api-keys/delete-api-key.md | 26 ++- .../api-reference/api-keys/enable-api-key.md | 29 ++- .../api-reference/api-keys/list-api-keys.md | 26 +-- www/docs/api-reference/overview.md | 6 +- .../search-apis/batched-queries.md | 17 +- .../interpreting-responses/highlighting.md | 4 +- .../interpreting-responses/metadata.md | 2 +- .../interpreting-responses/scores.md | 27 +-- www/docs/api-reference/search-apis/search.md | 13 +- 21 files changed, 319 insertions(+), 298 deletions(-) diff --git a/www/docs/api-reference/admin-apis/admin.md b/www/docs/api-reference/admin-apis/admin.md index 63f84cd2c..c2180393d 100644 --- a/www/docs/api-reference/admin-apis/admin.md +++ b/www/docs/api-reference/admin-apis/admin.md @@ -13,7 +13,8 @@ The Vectara Console is a good way for you to get started with exposes a REST endpoint at the following URL -to update the status of a corpus: +to compute the account size: https:///v1/compute-account-size ### Compute Account Size Example diff --git a/www/docs/api-reference/admin-apis/corpus/compute-corpus-size.md b/www/docs/api-reference/admin-apis/corpus/compute-corpus-size.md index 8d6f6c5fe..275ad5607 100644 --- a/www/docs/api-reference/admin-apis/corpus/compute-corpus-size.md +++ b/www/docs/api-reference/admin-apis/corpus/compute-corpus-size.md @@ -7,7 +7,7 @@ sidebar_label: Compute Corpus Size API Definition import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Compute Corpus Size endpoint lets you view the amount of quota consumed +The Compute Corpus Size API lets you view the amount of quota consumed by a corpus. This capability is useful for administrators to track and monitor the amount of usage for specific corpora. For example, you manage multiple tenants and determine that a user consumed too much quota and you might decide @@ -37,7 +37,7 @@ values. ### Compute Corpus Size REST Endpoint Address exposes a REST endpoint at the following URL -to update the status of a corpus: +to compute the size of a corpus: https:///v1/compute-corpus-size ### Compute Corpus Size Example diff --git a/www/docs/api-reference/admin-apis/corpus/list-documents.md b/www/docs/api-reference/admin-apis/corpus/list-documents.md index 40e96faf1..02ba40d5f 100644 --- a/www/docs/api-reference/admin-apis/corpus/list-documents.md +++ b/www/docs/api-reference/admin-apis/corpus/list-documents.md @@ -7,7 +7,7 @@ sidebar_label: List Documents API Definition import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The List Documents endpoint lets you view the Document IDs and their metadata +The List Documents API lets you view the Document IDs and their metadata in a corpus. This is useful for viewing documents indexed so far and helping you decide to remove documents that are no longer needed. It helps you manage the document lifecycle in your environent. @@ -19,8 +19,8 @@ capabilities into their applications. :::tip -Check out our [interactive API Playground](/docs/rest-api/list-documents) that lets you experiment with this -REST endpoint to manage your documents. +Check out our [**interactive API Playground**](/docs/rest-api/list-documents) that lets you experiment with this +REST endpoint to list your documents. ::: @@ -43,7 +43,7 @@ configure up to 1000. ### List Documents REST Endpoint Address exposes a REST endpoint at the following URL -to update the status of a corpus: +to list documents: https:///v1/list-documents ### List Documents Request Example diff --git a/www/docs/api-reference/admin-apis/corpus/read-corpus.md b/www/docs/api-reference/admin-apis/corpus/read-corpus.md index f55b9db99..6ae3172f1 100644 --- a/www/docs/api-reference/admin-apis/corpus/read-corpus.md +++ b/www/docs/api-reference/admin-apis/corpus/read-corpus.md @@ -7,7 +7,7 @@ sidebar_label: Read Corpus API Definition import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Read Corpus endpoint lets you view detailed information about corpora +The Read Corpus API lets you view detailed information about corpora within your account. It enables you to view different aspects about the corpus including basic information like the ID, name, whether it is enabled or disabled, and other metadata. You can also view the corpus size, associated @@ -29,7 +29,7 @@ because of information returned by this endpoint. :::tip Check out our [**interactive API Playground**](/docs/rest-api/read-corpus) that lets you experiment with this -REST endpoint to manage your corpus details. +REST endpoint to read your corpus details. ::: @@ -52,7 +52,7 @@ API keys with a specific corpus. ### Read Corpus REST Endpoint Address exposes a REST endpoint at the following URL -to ingest content into a corpus: +to read information about the corpus: https:///v1/read-corpus ### Read Corpus Request Example diff --git a/www/docs/api-reference/admin-apis/corpus/update-corpus-enablement.md b/www/docs/api-reference/admin-apis/corpus/update-corpus-enablement.md index 8676d7fb1..459f6a233 100644 --- a/www/docs/api-reference/admin-apis/corpus/update-corpus-enablement.md +++ b/www/docs/api-reference/admin-apis/corpus/update-corpus-enablement.md @@ -8,7 +8,7 @@ import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Update Corpus Enablement endpoint lets you enable or disable a corpus. +The Update Corpus Enablement API lets you enable or disable a corpus. This is useful to manage the availability of data within the system, such as when you need to take the corpus offline without having to delete the corpus. @@ -36,7 +36,7 @@ The request to enable or disable a corpus requires the following parameters: ### Update Corpus Enablement REST Endpoint Address exposes a REST endpoint at the following URL -to update the status of a corpus: +to enable or disable a corpus: https:///v1/update-corpus-enablement ### Update Corpus Enablement Request Example diff --git a/www/docs/api-reference/admin-apis/create-corpus.md b/www/docs/api-reference/admin-apis/create-corpus.md index c5942762b..d3daa8ec4 100644 --- a/www/docs/api-reference/admin-apis/create-corpus.md +++ b/www/docs/api-reference/admin-apis/create-corpus.md @@ -1,62 +1,99 @@ --- id: create-corpus -title: Create Corpus +title: Create Corpus API Definition sidebar_label: Create Corpus API Definition --- import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Create Corpus endpoint lets you create a corpus that contains specific -properties and attributes. -## Create Corpus REST Endpoint +The Create Corpus API lets you create a corpus that contains specific +properties and attributes. A corpus is a container where you upload your data +to be ingested for querying. - exposes a REST endpoint at the following URL -to ingest content into a corpus: -https:///v1/create-corpus +:::tip -### Create Corpus Request Headers +Check out our [**interactive API Playground**](/docs/rest-api/create-corpus) that lets +you experiment with this REST endpoint to create a corpus. -To interact with the Create Corpus service via REST calls, you need the following -headers: +::: -* `customer_id` is the customer ID to use for the request. -* JWT token as your `Bearer Token` -* (Optional) `grpc-timeout` lets you specify how long to wait for the calls - that have the potential to take longer to process. We recommend - `-H "grpc-timeout: 30S"` - -### Create Corpus Request Body +## Create Corpus Request Body and Response Only the `name` and `description` fields are mandatory when creating a corpus. +The response message returns a unique id, `corpus_id`, by which the corpus can +be subsequently referenced. + +:::note + +The name does not need to be unique within an account. + +::: + +In order to reference metadata in [filter expressions](/docs/learn/metadata-search-filtering/filter-overview), the +referenceable attributes must be declared at creation time in the **filter +attributes**. This list cannot be changed once the corpus is created. + +For information on **custom dimensions** please see +[Custom Dimensions](/docs/learn/semantic-search/add-custom-dimensions). +Like filter attributes, custom dimensions cannot be changed after the corpus is created. + + +## Filter Attributes Definition + +The `filterAttributes` object must specify a `name`, and a `level` which indicates +whether it exists in the document or part level metadata. At indexing time, +metadata with this name will be extracted and made available for filter +expressions to operate on. + +If `indexed` is true, the system will build an index on the extracted values +to further improve the performance of filter expressions involving the +attribute. + +Finally, filter attributes must specify a `type`, which is validated when +documents are indexed. The four supported types are `integer`, which stores +signed whole-number values up to eight bytes in length; `real`, for storing +floating point values in [IEEE 754 8-byte format][1]; `text` for storing +textual strings in [UTF-8 encoding][2], and `boolean` for storing true/false +values. + +[1]: https://en.wikipedia.org/wiki/Double-precision_floating-point_format +[2]: https://en.wikipedia.org/wiki/UTF-8 + + +## REST Example + +### Create Corpus REST Endpoint + + exposes a REST endpoint at the following URL +to create a corpus: +https:///v1/create-corpus + +### Create Corpus Request Body + ```json { "corpus": { - "id": 0, - "name": "string", - "description": "string", - "dtProvision": "string", + "id": 1, + "name": "NHL Rules", + "description": "Contains rulebooks for the NHL", + "dtProvision": "", "enabled": true, "swapQenc": true, "swapIenc": true, "textless": true, "encrypted": true, - "encoderId": "string", + "encoderId": "1", "metadataMaxBytes": 0, "customDimensions": [ - { - "name": "string", - "description": "string", - "servingDefault": 0, - "indexingDefault": 0 - } + {} ], "filterAttributes": [ { - "name": "string", - "description": "string", + "name": "name-of-field", + "description": "Description about the name", "indexed": true, "type": "FILTER_ATTRIBUTE_TYPE__UNDEFINED", "level": "FILTER_ATTRIBUTE_LEVEL__UNDEFINED" @@ -66,39 +103,25 @@ Only the `name` and `description` fields are mandatory when creating a corpus. } ``` -The response message returns a unique id, `corpus_id`, by which the corpus can -be subsequently referenced. Note that the name needn't be unique within an -account. +## gRPC Example -In order to reference metadata in [filter expressions](/docs/learn/metadata-search-filtering/filter-overview), the -referenceable attributes must be declared at creation time in the **filter -attributes**. This list cannot be changed once the corpus is created. - -For information on **custom dimensions** please see -[Custom Dimensions](/docs/learn/semantic-search/add-custom-dimensions). -Like filter attributes, custom dimensions cannot be changed after the corpus is created. +You can find the full Create Corpus gRPC definition +at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto). ```protobuf -message CreateCorpusRequest { - Corpus corpus = 1; -} - -message CreateCorpusResponse { - // The corpus id that was created. - uint32 corpus_id = 1; - Status status = 2; -} - message Corpus { - // The corpus id. + // The Corpus ID. + // This value is ignored during Corpus creation. uint32 id = 1; // The name of the corpus. string name = 2; // A description for the corpus. string description = 3; // The time at which the corpus was provisioned. + // This value is ignored during Corpus creation. int64 dt_provision = 4; // Whether the corpus is enabled for use or not. + // This value is ignored during Corpus creation. bool enabled = 5; @@ -127,54 +150,3 @@ message Corpus { repeated FilterAttribute filter_attributes = 14; } ``` - -#### Filter Attribute - -A filter attribute must specify a **name**, and a **level** which indicates -whether it exists in the document or part level metadata. At indexing time, -metadata with this name will be extracted and made available for filter -expressions to operate on. - -If **indexed** is true, the system will build an index on the extracted values -to further improve the performance of filter expressions involving the -attribute. - -Finally, filter attributes must specify a **type**, which is validated when -documents are indexed. The four supported types are **integer**, which stores -signed whole-number values up to eight bytes in length; **real**, for storing -floating point values in [IEEE 754 8-byte format][1]; **text** for storing -textual strings in [UTF-8 encoding][2], and **boolean** for storing true/false -values. - -[1]: https://en.wikipedia.org/wiki/Double-precision_floating-point_format -[2]: https://en.wikipedia.org/wiki/UTF-8 - - -``` -message FilterAttribute { - // Name of the field, as seen in metadata. - string name = 5; - // An optional description. - string description = 10; - // Whether the field is indexed for maximum query speed. - bool indexed = 15; - // The data type of the attribute. - FilterAttributeType type = 20; - // Whether the attribute lives at the document or part level. - FilterAttributeLevel level = 25; -} - -enum FilterAttributeType { - FILTER_ATTRIBUTE_TYPE__UNDEFINED = 0; - FILTER_ATTRIBUTE_TYPE__INTEGER = 5; - FILTER_ATTRIBUTE_TYPE__REAL = 15; - FILTER_ATTRIBUTE_TYPE__TEXT = 25; - FILTER_ATTRIBUTE_TYPE__BOOLEAN = 35; -} - -enum FilterAttributeLevel { - FILTER_ATTRIBUTE_LEVEL__UNDEFINED = 0; - FILTER_ATTRIBUTE_LEVEL__DOCUMENT = 5; // Document-level attribute - FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART = 10; // Part-level attribute -} -``` diff --git a/www/docs/api-reference/admin-apis/delete-corpus.md b/www/docs/api-reference/admin-apis/delete-corpus.md index b52fea76c..9e1eae37d 100644 --- a/www/docs/api-reference/admin-apis/delete-corpus.md +++ b/www/docs/api-reference/admin-apis/delete-corpus.md @@ -1,31 +1,45 @@ --- id: delete-corpus -title: Delete Corpus -sidebar_label: API Definition +title: Delete Corpus API Definition +sidebar_label: Delete Corpus API Definition --- import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; +The Delete Corpus API lets you delete a corpus from the account. + +## Delete Corpus Request Body + +To delete a corpus, specify the `customer_id` and `corpus_id`. Upon successful +completion, space quota consumed by the corpus will be freed, and the corpus +will no longer be useable for future indexing or querying. Note that the +`corpus_id` assigned to the corpus will not be reused. + +:::tip + +Check out our [**interactive API Playground**](/docs/rest-api/delete-corpus) that lets +you experiment with this REST endpoint to delete a corpus. + +::: + +## REST Example + +### Delete Corpus REST Endpoint + exposes a REST endpoint at the following URL -to ingest content into a corpus: +to delete a corpus: https:///v1/delete-corpus -This page describes the details of interacting with this endpoint. - -To delete a corpus, specify the `customer_id` and `corpus_id`. Upon -successful completion, space quota consumed by the corpus will be freed, -and the corpus will no longer be useable for future indexing or querying. -Note that the corpus_id assigned to the corpus will not be reused. - -```protobuf -message DeleteCorpusRequest { - // The customer id that contains the corpus to be deleted. - uint32 customer_id = 1; - // The corpus id to be deleted. - uint32 corpus_id = 2; -} -message DeleteCorpusResponse { - Status status = 1; +### Delete Corpus Request Body + +```json +{ + "corpusId": 5 } ``` + +## gRPC Example + +You can find the full Delete Corpus gRPC definition +at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto). diff --git a/www/docs/api-reference/admin-apis/manage-users/list-users.md b/www/docs/api-reference/admin-apis/manage-users/list-users.md index d9063a000..7c78d4b25 100644 --- a/www/docs/api-reference/admin-apis/manage-users/list-users.md +++ b/www/docs/api-reference/admin-apis/manage-users/list-users.md @@ -9,36 +9,23 @@ import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The List Users endpoint lets you list all users on your team and also their +The List Users API lets you list all users on your team and also their corpus access and customer-level authorizations. -Other activities -such as adding, deleting, enabling, disabling, resetting passwords, and -editing user roles are performed by the [Manage Users](/docs/api-reference/admin-apis/manage-users/manage-user) endpoint. +Other activities such as adding, deleting, enabling, disabling, resetting +passwords, and editing user roles are performed by the [Manage Users](/docs/api-reference/admin-apis/manage-users/manage-user) API. -## List Users Endpoint Address +:::tip - exposes a REST endpoint at the following URL -to index content into a corpus: -https:///v1/list-users - -## Manage Users from the API Playground - -Check out our [interactive API Playground](/docs/rest-api/list-users) that lets +Check out our [**interactive API Playground**](/docs/rest-api/list-users) that lets you experiment with this REST endpoint to manage users for your Vectara account. +::: -### Request Headers - -To interact with the List Users service via REST calls, you need the following headers: - -* `customer_id` is the Customer ID to use for the request -* An API Key or JWT Token as your authentication method +## List Users Request and Response -### Request Body - The List Users request body has the following parameters: * `list_users_type` - Specifies the type of users as none, all, or only to list users with acustomer account level. @@ -54,3 +41,63 @@ The List Users request body has the following parameters: "num_results": "5", } ``` + +## REST Example + +### List Users Endpoint Address + + exposes a REST endpoint at the following URL +to list users: +https:///v1/list-users + +### Request Body and Response + +```json +{ + "list_users_type": "LIST_USERS_TYPE__ALL", + "page_key": "", + "num_results": "5", +} +``` +You get the following response: + +```json +{ + "user": [ + { + "id": 1, + "sub": "xyz.....", + "handle": "user@vectara.com", + "type": "USER_TYPE__FEDERATED_USER", + "comment": "Account owner.", + "tsCreate": "1685481912", + "idCreate": 0, + "tsUpdate": "0", + "idUpdate": 0, + "email": "", + "userStatus": "USER_STATUS__NONE", + "role": [] + }, + { + "id": 2, + "sub": "abcde.....", + "handle": "NHL", + "type": "USER_TYPE__APP_CLIENT", + "comment": "OAuth for the Docs corpus", + "tsCreate": "1694584030", + "idCreate": 0, + "tsUpdate": "0", + "idUpdate": 0, + "email": "", + "userStatus": "USER_STATUS__NONE", + "role": [] + }, + ], + "pageKey": "", + "status": { + "code": "OK", + "statusDetail": "", + "cause": null + } +} +``` \ No newline at end of file diff --git a/www/docs/api-reference/admin-apis/manage-users/manage-user.md b/www/docs/api-reference/admin-apis/manage-users/manage-user.md index 70f095018..65bd974cd 100644 --- a/www/docs/api-reference/admin-apis/manage-users/manage-user.md +++ b/www/docs/api-reference/admin-apis/manage-users/manage-user.md @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Manage User endpoint lets you perform different user and team management +The Manage User API lets you perform different user and team management activities such as adding, deleting, enabling, disabling, and editing user roles. This capability is useful in scenarios that require dynamic team management. @@ -19,47 +19,31 @@ endpoint lets you streamline the onboarding process by programatically adding new users, assigning appropriate roles, and setting up access permissions. -## Manage User Endpoint Address +:::tip - exposes a REST endpoint at the following URL -to index content into a corpus: -https:///v1/manage-user - -## Manage Users from the API Playground - -Check out our [interactive API Playground](/docs/rest-api/manage-user) that lets +Check out our [**interactive API Playground**](/docs/rest-api/manage-user) that lets you experiment with this REST endpoint to manage users for your Vectara account. +::: -### Request Headers -To interact with the Manage User service via REST calls, you need the following headers: -* `customer_id` is the Customer ID to use for the request -* An API Key or JWT Token as your authentication method +## REST Example +### Manage User Endpoint Address + + exposes a REST endpoint at the following URL +to manage a user: +https:///v1/manage-user -### Request Body +### Manage User Request The Manage User request body requires the following parameters: * `handle` - Specifies the ID of the user. -* `type` - Specifies the type of user: - - `USER_TYPE__NONE` - A default user type, typically used as a placeholder. - - `USER_TYPE__USER` - A standard user type for users who will interact with the Vectara - platform. - - `USER_TYPE__FEDERATED_USER` - A user authenticated by an external identity provider - such as Google. - - `USER_TYPE__APP_CLIENT` - An application client and not individual users. These - application-level clients interact with the system. +* `type` - Specifies the type of user. * `email` -* `userActionType` - Specifies the type of action for the user: - - `USER_ACTION_TYPE__ADD` - - `USER_ACTION_TYPE__DELETE` - - `USER_ACTION_TYPE__DISABLE` - - `USER_ACTION_TYPE__ENABLE` - - `USER_ACTION_TYPE__RESET_PASSWORD` - - `USER_ACTION_TYPE__EDIT_ROLE` +* `userActionType` - Specifies the type of action for the user. ```json { diff --git a/www/docs/api-reference/admin-apis/reset-corpus.md b/www/docs/api-reference/admin-apis/reset-corpus.md index 918242ba4..d1d5055e4 100644 --- a/www/docs/api-reference/admin-apis/reset-corpus.md +++ b/www/docs/api-reference/admin-apis/reset-corpus.md @@ -1,28 +1,45 @@ --- id: reset-corpus -title: Reset Corpus -sidebar_label: API Definition +title: Reset Corpus API Definition +sidebar_label: Reset Corpus API Definition --- import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; - exposes a REST endpoint at the following URL -to reset a corpus: -https:///v1/reset-corpus -This page describes the details of interacting with this endpoint. +The Reset Corpus API lets you reset a corpus in the account. A reset purges +all the data within a corpus, but it leaves the corpus definition intact. + +## Reset Corpus Request Body To reset a corpus, specify the `customer_id` and `corpus_id`. Upon successful completion, space quota consumed by the corpus will be freed. -```protobuf -message ResetCorpusRequest { - uint32 customer_id = 1; - // The corpus id to reset. - uint32 corpus_id = 2; -} +:::tip + +Check out our [**interactive API Playground**](/docs/rest-api/reset-corpus) that lets +you experiment with this REST endpoint to reset a corpus. + +::: + +## REST Example + +### Reset Corpus REST Endpoint -message ResetCorpusResponse { - Status status = 1; + exposes a REST endpoint at the following URL +to reset a corpus: +https:///v1/reset-corpus + +### Reset Corpus Request Body + +```json +{ + "corpusId": 5 } ``` + +## gRPC Example + +You can find the full Reset Corpus gRPC definition +at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto). + diff --git a/www/docs/api-reference/api-keys/create-api-key.md b/www/docs/api-reference/api-keys/create-api-key.md index 53268da60..33f7374e5 100644 --- a/www/docs/api-reference/api-keys/create-api-key.md +++ b/www/docs/api-reference/api-keys/create-api-key.md @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Create API Key endpoint lets you create new API keys, which you can +The Create API Key API lets you create new API keys, which you can bind to one or multiple corpora. You can also decide whether to designate each key for specific access like only querying (read-only) or both querying and indexing (read-write). @@ -18,26 +18,22 @@ This capability is useful in scenarios where you have applications that require different levels of access to corpora data. For example, you might create a read-only API key for an application that only needs to query data. -## Create API Key Endpoint Address +:::tip - exposes a REST endpoint at the following URL -to index content into a corpus: -https:///v1/create-api-key - -## Create an API Key from the API Playground - -Check out our [interactive API Playground](/docs/rest-api/create-api-key) that lets +Check out our [**interactive API Playground**](/docs/rest-api/create-api-key) that lets you experiment with this REST endpoint to create API keys for your account. -### Request Headers +::: -To interact with the Index service via REST calls, you need the following -headers: +## REST Example -* `customer_id` is the customer ID to use for the request. -* An JWT token as your authentication method +### Create API Key Endpoint Address -### Request Body + exposes a REST endpoint at the following URL +to create an API key: +https:///v1/create-api-key + +### Create API Key Request Body The Create API Key request body requires the following parameters: * `description` - Provides details about the API key @@ -45,6 +41,8 @@ The Create API Key request body requires the following parameters: (default), `API_KEY_TYPE__SERVING`, or `API_KEY_TYPE__SERVING_INDEXING`. * `corpusId` - Specifies the corpus IDs where you want to bind the API key. +In this example, you create a default key. + ```json { "apiKeyData": [ diff --git a/www/docs/api-reference/api-keys/delete-api-key.md b/www/docs/api-reference/api-keys/delete-api-key.md index a50242e34..d3e7385c5 100644 --- a/www/docs/api-reference/api-keys/delete-api-key.md +++ b/www/docs/api-reference/api-keys/delete-api-key.md @@ -9,30 +9,26 @@ import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Delete API Key endpoint lets you delete one or more existing API keys. +The Delete API Key API lets you delete one or more existing API keys. This capability is useful for managing the lifecycle and security of API keys such as when they are no longer needed or when a key is compromised. -## Delete API Key Endpoint Address +:::tip - exposes a REST endpoint at the following URL -to index content into a corpus: -https:///v1/delete-api-key - -## Delete an API Key from the API Playground - -Check out our [interactive API Playground](/docs/rest-api/delete-api-key) that lets +Check out our [**interactive API Playground**](/docs/rest-api/delete-api-key) that lets you experiment with this REST endpoint to delete API keys from an account. -### Request Headers +::: -To interact with the Index service via REST calls, you need the following -headers: +## REST Example -* `customer_id` is the customer ID to use for the request. -* An JWT token as your authentication method +### Delete API Key Endpoint Address + + exposes a REST endpoint at the following URL +to delete an API key: +https:///v1/delete-api-key -### Request Body +### Delete API Key Request Body The Delete API Key request body requires the `keyID` of the API key you diff --git a/www/docs/api-reference/api-keys/enable-api-key.md b/www/docs/api-reference/api-keys/enable-api-key.md index ac04b87a3..0827371d5 100644 --- a/www/docs/api-reference/api-keys/enable-api-key.md +++ b/www/docs/api-reference/api-keys/enable-api-key.md @@ -9,33 +9,28 @@ import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Enable API Key endpoint lets you enable or disable specific API keys. You -can use this endpoint to temporarily disable access without deleting the key. +The Enable API Key API lets you enable or disable specific API keys. You +can use this API to temporarily disable access without deleting the key. This capability is useful for scenarios like maintenance windows. or when your team no longer requires access to a specific corpus. -## Enable API Key REST Endpoint +:::tip - exposes a REST endpoint at the following URL -to index content into a corpus: -https:///v1/enable-api-key - -## Enable an API Key from the API Playground - -Check out our [interactive API Playground](/docs/rest-api/enable-api-key) that lets +Check out our [**interactive API Playground**](/docs/rest-api/enable-api-key) that lets you experiment with this REST endpoint to enable and disable API keys. -### Request Headers +::: -To interact with the Index service via REST calls, you need the following -headers: +## REST Example -* `customer_id` is the customer ID to use for the request. -* An JWT token as your authentication method +### Enable API Key REST Endpoint + exposes a REST endpoint at the following URL +to enable an API key: +https:///v1/enable-api-key -### Request Body +### Enable API Key Request Body The Enable API Key request body requires the following parameters: * `keyID` - Specifies the ID of the API key @@ -46,7 +41,7 @@ The Enable API Key request body requires the following parameters: { "keyEnablement": [ { - "keyId": "6o59jjft9o02jtga72pjfv3qpn", + "keyId": "6o59jjft9o...........", "enable": true } ] diff --git a/www/docs/api-reference/api-keys/list-api-keys.md b/www/docs/api-reference/api-keys/list-api-keys.md index 93a84505a..c4206d64d 100644 --- a/www/docs/api-reference/api-keys/list-api-keys.md +++ b/www/docs/api-reference/api-keys/list-api-keys.md @@ -9,36 +9,30 @@ import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The List API Keys endpoint lists all existing API keys for a customer ID. +The List API Keys API lists all existing API keys for a customer ID. It also shows what corpora are accessed by these keys and with what permissions. This capability can provide insights into key usage and status and help you manage the lifecycle and security of your API keys. +:::tip -## List API Keys Endpoint Address - - exposes a REST endpoint at the following URL -to index content into a corpus: -https:///v1/list-api-keys - -## List the API Keys from the API Playground - -Check out our [interactive API Playground](/docs/rest-api/list-api-keys) that lets +Check out our [**interactive API Playground**](/docs/rest-api/list-api-keys) that lets you experiment with this REST endpoint to list API keys in an account. +::: -### Request Headers -To interact with the List API Keys service via REST calls, you need the -following headers: +## REST Example -* `customer_id` is the customer ID to use for the request. -* An JWT token as your authentication method +### List API Keys Endpoint Address + exposes a REST endpoint at the following URL +to list the API keys for a Customer ID: +https:///v1/list-api-keys -### Request Body +### List API Keys Request Body The List API Keys request body requires the following parameters: * `numResults` - Specifies the maximum number of results to return. diff --git a/www/docs/api-reference/overview.md b/www/docs/api-reference/overview.md index 6732f2a97..c2e03d32c 100644 --- a/www/docs/api-reference/overview.md +++ b/www/docs/api-reference/overview.md @@ -12,9 +12,9 @@ import {Config} from '@site/docs/definitions.md'; Everything in is driven by APIs. This section serves as a roadmap to understanding and using our [gRPC APIs](/docs/api-reference/protobuf-definitions) and -[REST APIs](/docs/api-reference/rest) for indexing, searching, and administrative tasks. -Before getting into more details, we -recommend that you have a basic understanding of API concepts. +[REST APIs](/docs/api-reference/rest) for [indexing](/docs/learn/select-ideal-indexing-api), [querying](/docs/api-reference/search-apis/search), and administrative tasks +such as [managing user access](/docs/api-reference/admin-apis/manage-users/manage-user) and [corpora](/docs/api-reference/admin-apis/admin). Before getting into more +details, we recommend that you have a basic understanding of API concepts. ## :star2: Ready to Dive In? Check Out Our API Playground! :star2: diff --git a/www/docs/api-reference/search-apis/batched-queries.md b/www/docs/api-reference/search-apis/batched-queries.md index e11e826b8..9e7b656ea 100644 --- a/www/docs/api-reference/search-apis/batched-queries.md +++ b/www/docs/api-reference/search-apis/batched-queries.md @@ -1,7 +1,7 @@ --- id: batched-queries -title: Batching Multiple Queries -sidebar_label: Batched Queries +title: Batch Multiple Queries +sidebar_label: Batch Multiple Queries --- import Tabs from '@theme/Tabs'; @@ -11,8 +11,10 @@ import {vars} from '@site/static/variables.json'; Some applications may be designed to be powered by different queries in different parts of the UI. In order to decrease the number of network round -trips (and thereby the net latency), you may want to issue those multiple -queries to the system with a single API call. +trips (and thereby the net latency), you may want to batch those multiple +queries with a single API call. + +## Query Array in a Request This pattern can be done in by sending an array of queries in a single request, as in: @@ -38,11 +40,10 @@ separate query for billing purposes. ::: -## Responses +## Batched Query Responses -When you a query , you get back an array of results. -This array is to assist in using -[Batched Query](/docs/api-reference/search-apis/batched-queries.md), +When you query , you get back an array of results. +This array is to assist in using batched queries. ```jsx { diff --git a/www/docs/api-reference/search-apis/interpreting-responses/highlighting.md b/www/docs/api-reference/search-apis/interpreting-responses/highlighting.md index 36399db42..06e0b6f36 100644 --- a/www/docs/api-reference/search-apis/interpreting-responses/highlighting.md +++ b/www/docs/api-reference/search-apis/interpreting-responses/highlighting.md @@ -1,14 +1,14 @@ --- id: highlighting title: Highlighting and Snippet Extraction -sidebar_label: Highlighting +sidebar_label: Highlighting and Snippet Extraction --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; -When you receive search results from , alongside the +When you receive query results from , alongside the result, you'll receive a values for `section` and `offset`. For example: ```json showLineNumbers diff --git a/www/docs/api-reference/search-apis/interpreting-responses/metadata.md b/www/docs/api-reference/search-apis/interpreting-responses/metadata.md index daf94093d..9e8a0efb8 100644 --- a/www/docs/api-reference/search-apis/interpreting-responses/metadata.md +++ b/www/docs/api-reference/search-apis/interpreting-responses/metadata.md @@ -1,7 +1,7 @@ --- id: metadata title: Reading Metadata -sidebar_label: Metadata +sidebar_label: Reading Metadata --- import Tabs from '@theme/Tabs'; diff --git a/www/docs/api-reference/search-apis/interpreting-responses/scores.md b/www/docs/api-reference/search-apis/interpreting-responses/scores.md index 9a0c039ca..1f3f9e03e 100644 --- a/www/docs/api-reference/search-apis/interpreting-responses/scores.md +++ b/www/docs/api-reference/search-apis/interpreting-responses/scores.md @@ -1,19 +1,17 @@ --- id: interpreting-scores title: Interpreting Scores -sidebar_label: Scores +sidebar_label: Interpreting Scores --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; -## Overview - -Like all search systems, scores documents on how -relevant they are to the query. And like all search systems, -it's important to understand the scoring system and how it changes based on -the controls and query parameters you've provided. +Like all information retrieval systems, scores documents on how +relevant they are to the query. It's important to understand the scoring +system and how it changes based on the controls and query parameters you have +provided. Out of the box scores in : 1. Can be either positive or negative @@ -26,8 +24,13 @@ Out of the box scores in : See the sections below on "standard" and "reranked" results for details on how they differ and how to use them best. -Note that provides an important control that can affect scores: -[custom dimensions](/docs/learn/semantic-search/add-custom-dimensions), which allow you to boost or bury results based on metadata. +:::note + +Vectara provides an important control that can affect scores: +[**custom dimensions**](/docs/learn/semantic-search/add-custom-dimensions), which allow you to boost +or bury results based on metadata. + +::: ## Comparison With Keyword Systems @@ -84,7 +87,7 @@ results as no longer very relevant. However, as a general rule, scores less than 0.1 tend to be of low quality and can typically be safely removed/ignored. ## Reranked Results Response -Scores from after reranking will be scored on a +Scores from after [reranking](/docs/api-reference/search-apis/reranking) are scored on a scale from -infinity to +infinity. Internally, the numbers returned from the reranker are derived from a logarithmic scoring system, which means that in practice, scores much higher than 10 or much lower than -10 should be rare. @@ -93,6 +96,4 @@ As with standard results, there's no hard rule around when to cut off results, but scores above around 2.5 or so tend to be pretty good, though we advise users to test with their own data and some sample queries. -Note that the reranker is *currently* English-only, so if you get very low -scores, you might want to check that your content is in English and disable -the reranker where that isn't the case. + diff --git a/www/docs/api-reference/search-apis/search.md b/www/docs/api-reference/search-apis/search.md index d6fd1527d..32b630506 100644 --- a/www/docs/api-reference/search-apis/search.md +++ b/www/docs/api-reference/search-apis/search.md @@ -1,7 +1,7 @@ --- id: search -title: Search API Definition -sidebar_label: Search API Definition +title: Query API Definition +sidebar_label: Query API Definition --- import Tabs from '@theme/Tabs'; @@ -9,10 +9,10 @@ import TabItem from '@theme/TabItem'; import {Config} from '@site/docs/definitions.md'; import {vars} from '@site/static/variables.json'; -The Search endpoint lets you perform a query while defining its parameters +The Query API lets you perform a query while defining its parameters that specify the query text, pagination details, metadata filters, and other -settings that enable application builders to tailor their queries to specific -use cases. +search settings that enable application builders to tailor their queries to +specific use cases. After you index data into one or more corpora, you can run queries and display the results. This page provides a detailed reference for how @@ -21,7 +21,8 @@ filtering, reranking, Retrieval Augmented Generation (RAG), and hybrid search. :::tip -Check out our [**interactive API Playground**](/docs/rest-api/query) that lets you experiment with this REST endpoint to manage your corpus details. +Check out our [**interactive API Playground**](/docs/rest-api/query) that lets +you experiment with this REST endpoint to query your corpus to search your data. ::: From 5157fe6bd9228c234819550d53fb266d648858a7 Mon Sep 17 00:00:00 2001 From: Paul Wozniczka <25128922+pwoznic@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:36:26 -0600 Subject: [PATCH 3/6] Fix spacing --- www/sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/sidebars.js b/www/sidebars.js index 501becec7..ee17b44c8 100644 --- a/www/sidebars.js +++ b/www/sidebars.js @@ -219,7 +219,7 @@ module.exports = { 'api-reference/admin-apis/create-corpus', { type: 'category', - label: 'Create Corpus REST Examples', + label: 'Create Corpus REST Examples', items: [ 'getting-started-samples/RestCreateCorpus.java', 'getting-started-samples/create_corpus.js', From 52b29cbd85fbe9157a852fb4aa504a9ec74abaf6 Mon Sep 17 00:00:00 2001 From: Paul Wozniczka <25128922+pwoznic@users.noreply.github.com> Date: Fri, 26 Jan 2024 16:59:16 -0600 Subject: [PATCH 4/6] Update sidebar --- www/sidebars.js | 214 ++++++++++++++++++++++++------------------------ 1 file changed, 107 insertions(+), 107 deletions(-) diff --git a/www/sidebars.js b/www/sidebars.js index ee17b44c8..e86d4e138 100644 --- a/www/sidebars.js +++ b/www/sidebars.js @@ -173,164 +173,164 @@ module.exports = { label: "API Reference", collapsed: true, items: [ - 'api-reference/api-overview', - 'api-reference/protobuf-definitions', - 'api-reference/rest', + "api-reference/api-overview", + "api-reference/protobuf-definitions", + "api-reference/rest", { - type: `category`, - label: `Account Admin APIs`, + type: "category", + label: "Account Admin APIs", items: [ - 'api-reference/admin-apis/compute-account-size' + "api-reference/admin-apis/compute-account-size" ] }, { - type: `category`, - label: `Access Admin APIs`, + type: "category", + label: "Access Admin APIs", items: [ { - type: 'category', - label: 'User Admin APIs', + type: "category", + label: "User Admin APIs", items: [ - 'api-reference/admin-apis/manage-users/list-users', - 'api-reference/admin-apis/manage-users/manage-user', + "api-reference/admin-apis/manage-users/list-users", + "api-reference/admin-apis/manage-users/manage-user", ] }, { - type: 'category', - label: 'API Key Admin APIs', + type: "category", + label: "API Key Admin APIs", items: [ - 'api-reference/api-keys/create-api-key', - 'api-reference/api-keys/delete-api-key', - 'api-reference/api-keys/list-api-keys', - 'api-reference/api-keys/enable-api-key', + "api-reference/api-keys/create-api-key", + "api-reference/api-keys/delete-api-key", + "api-reference/api-keys/list-api-keys", + "api-reference/api-keys/enable-api-key", ] }, ] }, { - type: 'category', - label: 'Corpus Admin APIs', + type: "category", + label: "Corpus Admin APIs", items: [ - 'api-reference/admin-apis/admin', + "api-reference/admin-apis/admin", { - type: 'category', - label: 'Create Corpus', + type: "category", + label: "Create Corpus", items: [ - 'api-reference/admin-apis/create-corpus', + "api-reference/admin-apis/create-corpus", { - type: 'category', - label: 'Create Corpus REST Examples', + type: "category", + label: "Create Corpus REST Examples", items: [ - 'getting-started-samples/RestCreateCorpus.java', - 'getting-started-samples/create_corpus.js', - 'getting-started-samples/createCorpus.php', - 'getting-started-samples/rest_create_corpus.py' + "getting-started-samples/RestCreateCorpus.java", + "getting-started-samples/create_corpus.js", + "getting-started-samples/createCorpus.php", + "getting-started-samples/rest_create_corpus.py" ] } ] }, { - type: 'category', - label: 'Delete Corpus', + type: "category", + label: "Delete Corpus", items: [ - 'api-reference/admin-apis/delete-corpus', + "api-reference/admin-apis/delete-corpus", { - type: 'category', - label: 'Delete Corpus REST Examples', + type: "category", + label: "Delete Corpus REST Examples", items: [ - 'getting-started-samples/RestDeleteCorpus.cs', - 'getting-started-samples/delete_corpus.js', - 'getting-started-samples/deleteCorpus.php', - 'getting-started-samples/rest_delete_corpus.py' + "getting-started-samples/RestDeleteCorpus.cs", + "getting-started-samples/delete_corpus.js", + "getting-started-samples/deleteCorpus.php", + "getting-started-samples/rest_delete_corpus.py" ] } ] }, { - type: 'category', - label: 'Reset Corpus', + type: "category", + label: "Reset Corpus", items: [ - 'api-reference/admin-apis/reset-corpus', + "api-reference/admin-apis/reset-corpus", { - type: 'category', - label: 'Reset Corpus REST Examples', + type: "category", + label: "Reset Corpus REST Examples", items: [ - 'getting-started-samples/RestResetCorpus.cs', - 'getting-started-samples/reset_corpus.js', - 'getting-started-samples/resetCorpus.php', - 'getting-started-samples/rest_reset_corpus.py' + "getting-started-samples/RestResetCorpus.cs", + "getting-started-samples/reset_corpus.js", + "getting-started-samples/resetCorpus.php", + "getting-started-samples/rest_reset_corpus.py" ] } ] }, - 'api-reference/admin-apis/corpus/update-corpus-enablement', - 'api-reference/admin-apis/corpus/read-corpus', - 'api-reference/admin-apis/corpus/compute-corpus-size', + "api-reference/admin-apis/corpus/update-corpus-enablement", + "api-reference/admin-apis/corpus/read-corpus", + "api-reference/admin-apis/corpus/compute-corpus-size", ] }, { - type: 'category', - label: 'Document Admin APIs', + type: "category", + label: "Document Admin APIs", items: [ - 'api-reference/admin-apis/corpus/list-documents', - 'api-reference/indexing-apis/deleting-documents', + "api-reference/admin-apis/corpus/list-documents", + "api-reference/indexing-apis/deleting-documents", { - type: 'category', - label: 'Delete Document REST Examples', + type: "category", + label: "Delete Document REST Examples", items: [ - 'getting-started-samples/RestDeleteDocument.cs', - 'getting-started-samples/RestDeleteDocument.java', - 'getting-started-samples/delete_document.js', - 'getting-started-samples/deleteDocument.php', - 'getting-started-samples/rest_delete_document.py', + "getting-started-samples/RestDeleteDocument.cs", + "getting-started-samples/RestDeleteDocument.java", + "getting-started-samples/delete_document.js", + "getting-started-samples/deleteDocument.php", + "getting-started-samples/rest_delete_document.py", ] }, ] }, { - type: 'category', - label: 'Indexing APIs', + type: "category", + label: "Indexing APIs", items: [ { - type: 'category', - label: 'Standard Indexing API', + type: "category", + label: "Standard Indexing API", items: [ - 'api-reference/indexing-apis/indexing', + "api-reference/indexing-apis/indexing", { - type: 'category', - label: 'Standard Indexing REST Examples', + type: "category", + label: "Standard Indexing REST Examples", items: [ - 'getting-started-samples/RestIndexData.cs', - 'getting-started-samples/RestIndex.java', - 'getting-started-samples/index_document.js', - 'getting-started-samples/indexDocument.php', - 'getting-started-samples/rest_index_document.py', + "getting-started-samples/RestIndexData.cs", + "getting-started-samples/RestIndex.java", + "getting-started-samples/index_document.js", + "getting-started-samples/indexDocument.php", + "getting-started-samples/rest_index_document.py", ] }, ] }, { - type: 'category', - label: 'Low-level API', + type: "category", + label: "Low-level API", items: [ - 'api-reference/indexing-apis/core_indexing' + "api-reference/indexing-apis/core_indexing" ] }, { - type: 'category', - label: 'File Upload API', + type: "category", + label: "File Upload API", items: [ - 'api-reference/indexing-apis/file-upload/file-upload', - 'api-reference/indexing-apis/file-upload/format-for-upload', - 'api-reference/indexing-apis/file-upload/file-upload-filetypes', + "api-reference/indexing-apis/file-upload/file-upload", + "api-reference/indexing-apis/file-upload/format-for-upload", + "api-reference/indexing-apis/file-upload/file-upload-filetypes", { - type: 'category', - label: 'File Upload REST Examples', + type: "category", + label: "File Upload REST Examples", items: [ - 'getting-started-samples/RestUploadFile.java', - 'getting-started-samples/upload_file.js', - 'getting-started-samples/uploadFile.php', - 'getting-started-samples/rest_upload_file.py', + "getting-started-samples/RestUploadFile.java", + "getting-started-samples/upload_file.js", + "getting-started-samples/uploadFile.php", + "getting-started-samples/rest_upload_file.py", ] }, ] @@ -338,36 +338,36 @@ module.exports = { ], }, { - type: 'category', - label: 'Query APIs', + type: "category", + label: "Query APIs", items: [ { - type: 'category', - label: 'Standard Query API', + type: "category", + label: "Standard Query API", items: [ - 'api-reference/search-apis/search', + "api-reference/search-apis/search", { - type: 'category', - label: 'Standard Query REST Examples', + type: "category", + label: "Standard Query REST Examples", items: [ - 'getting-started-samples/RestQueryData.cs', - 'getting-started-samples/RestQuery.java', - 'getting-started-samples/query.js', - 'getting-started-samples/queryData.php', - 'getting-started-samples/rest_query.py', + "getting-started-samples/RestQueryData.cs", + "getting-started-samples/RestQuery.java", + "getting-started-samples/query.js", + "getting-started-samples/queryData.php", + "getting-started-samples/rest_query.py", ] }, ] }, - 'api-reference/search-apis/reranking', - 'api-reference/search-apis/batched-queries', + "api-reference/search-apis/reranking", + "api-reference/search-apis/batched-queries", { - type: 'category', - label: 'Interpreting Responses', + type: "category", + label: "Interpreting Responses", items: [ - 'api-reference/search-apis/interpreting-responses/metadata', - 'api-reference/search-apis/interpreting-responses/interpreting-scores', - 'api-reference/search-apis/interpreting-responses/highlighting', + "api-reference/search-apis/interpreting-responses/metadata", + "api-reference/search-apis/interpreting-responses/interpreting-scores", + "api-reference/search-apis/interpreting-responses/highlighting", ], }, ], From 95313e16f24e091d0737574c9c4749594ed2ce82 Mon Sep 17 00:00:00 2001 From: Paul Wozniczka <25128922+pwoznic@users.noreply.github.com> Date: Sun, 28 Jan 2024 15:03:32 -0600 Subject: [PATCH 5/6] Update overview --- www/docs/api-reference/overview.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/www/docs/api-reference/overview.md b/www/docs/api-reference/overview.md index c2e03d32c..0601c80a0 100644 --- a/www/docs/api-reference/overview.md +++ b/www/docs/api-reference/overview.md @@ -31,18 +31,13 @@ and other key concepts: * **gRPC APIs:** Understand the basics of gRPC (Remote Procedure Call) such as the advantages with performance, code generation, and how it uses Protocol - Buffers (**.proto** files) for schema defnitions. - - You can [download the `.proto` files](https://github.com/vectara/protos/tree/main) directly from Github. - For example, [`serving.proto`](https://github.com/vectara/protos/blob/main/serving.proto) + Buffers (**.proto** files) for schema defnitions. You can [download the `.proto` files](https://github.com/vectara/protos/tree/main) directly + from Github. For example, [`serving.proto`](https://github.com/vectara/protos/blob/main/serving.proto) provides the message definitions for running queries. - * **RESTful APIs:** Understand the principles of Representational State Transfer (REST) and why it's commonly used in web services. Make sure to also - understand how it differs from gRPC. - - For example, review the [Java example](/docs/getting-started-samples/RestIndex.java) for our Standard Indexing API. - + understand how it differs from gRPC. For example, review the [Java example](/docs/getting-started-samples/RestIndex.java) for our + Standard Indexing API. * **HTTP Methods:** Become familar with HTTP methods like GET, POST, PUT, and DELETE. * **gRPC Methods:** Become familar with gRPC methods like server streaming, client streaming, and bidirectional streaming. @@ -65,9 +60,9 @@ APIs and some organizations still struggle with using HTTP/2.0 due to firewalls. ### REST API If you'd like more details about how to use our REST APIs, including details on -our OpenAPI specification and services, a good place to start is the [REST](rest) +our OpenAPI specification and services, a good place to start is the [REST APIs](rest) page. ### gRPC API If you'd like more details about how to use our gRPC APIs, including details on -how to generate strongly typed clients, see our [gRPC](protobuf-definitions) page. \ No newline at end of file +how to generate strongly typed clients, see our [gRPC APIs](protobuf-definitions) page. \ No newline at end of file From 30b51a0bf83029fabdec5cab24a7f016ebbd8a58 Mon Sep 17 00:00:00 2001 From: Paul Wozniczka <25128922+pwoznic@users.noreply.github.com> Date: Tue, 30 Jan 2024 15:15:47 -0600 Subject: [PATCH 6/6] Update blog link --- www/docs/api-reference/admin-apis/admin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/docs/api-reference/admin-apis/admin.md b/www/docs/api-reference/admin-apis/admin.md index c2180393d..2773fd361 100644 --- a/www/docs/api-reference/admin-apis/admin.md +++ b/www/docs/api-reference/admin-apis/admin.md @@ -14,7 +14,7 @@ you're ready to integrate the platform more deeply into your application, the Corpus Admin APIs allow you to programmatically manipulate corpora and perform many other operations within the system. These APIs enable new workflows for organizations, like managing corpora and tracking usage of accounts -and corpora. Check out this [blog post about managing multi-tenancy](https://vectara.com/managing-multi-tenancy-with-vectaras-new-management-apis/) for more details. +and corpora. Check out this [blog post about managing multi-tenancy](https://vectara.com/blog/managing-multi-tenancy-with-vectaras-new-management-apis/) for more details. :::tip