Merge pull request #225461 from HeidiSteen/heidist-fix

[azure search] Refresh REST quickstart

Author: Maggiemouse1

articles/search/media/search-get-started-rest/postman-collection-variables.png

@@ -9,23 +9,21 @@ ms.author: heidist
 ms.service: cognitive-search
 ms.topic: quickstart
 ms.devlang: rest-api
-ms.date: 10/25/2022
+ms.date: 01/27/2023
 ms.custom: mode-api
 ---
 
 # Quickstart: Create an Azure Cognitive Search index using REST APIs
 
-This article explains how to formulate REST API requests interactively using the [Azure Cognitive Search REST APIs](/rest/api/searchservice) and an API client for sending and receiving requests. 
-
-If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
+This article explains how to formulate requests interactively using the [Azure Cognitive Search REST APIs](/rest/api/searchservice) and a REST client for sending and receiving requests. 
 
 The article uses the Postman desktop application. You can [download and import a Postman collection](https://github.com/Azure-Samples/azure-search-postman-samples/tree/master/Quickstart) if you prefer to use predefined requests.
 
-## Prerequisites
+If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
 
-The following services and tools are required for this quickstart. 
+## Prerequisites
 
-+ [Postman desktop app](https://www.getpostman.com/) is used for sending requests to Azure Cognitive Search.
++ [Postman desktop app](https://www.getpostman.com/), used for sending requests to Azure Cognitive Search.
 
 + [Create an Azure Cognitive Search service](search-create-service-portal.md) or [find an existing service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) under your current subscription. You can use a free service for this quickstart. 
 
@@ -43,46 +41,43 @@ All requests require an api-key on every request sent to your service. Having a
 
 ## Connect to Azure Cognitive Search
 
-In this section, use your web tool of choice to set up connections to Azure Cognitive Search. Each tool persists request header information for the session, which means you only have to enter the api-key and Content-Type once.
+Connection information is specified in the URI endpoint. Collection variables are used to represent the search service name and API keys. A typical URI in this quickstart looks like this:
 
-For either tool, you need to choose a command (GET, POST, PUT, and so forth), provide a URL endpoint, and for some tasks, provide JSON in the body of the request. Replace the search service name (YOUR-SEARCH-SERVICE-NAME)  with a valid value. Add `$select=name` to return just the name of each index. 
+```http
+https://{{service-name}}.search.windows.net/indexes/hotels-quickstart?api-version=2020-06-30
+```
 
-> `https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2020-06-30&$select=name`
+Notice the HTTPS prefix, the name of the service (variable, the name of an object (in this case, the name of an index in the indexes collection), and the [api-version](search-api-versions.md). The api-version is a required.
 
-Notice the HTTPS prefix, the name of the service, the name of an object (in this case, the indexes collection), and the [api-version](search-api-versions.md). The api-version is a required, lowercase string specified as `?api-version=2020-06-30` for the current version. API versions are updated regularly. Including the api-version on each request gives you full control over which one is used.  
+Request header composition includes two elements: `Content-Type` and the `api-key` used to authenticate to Azure Cognitive Search. The `api-key` is specified as variable, and it's also required.
 
-Request header composition includes two elements: `Content-Type` and the `api-key` used to authenticate to Azure Cognitive Search. Replace the admin API key (YOUR-AZURE-SEARCH-ADMIN-API-KEY) with a valid value. 
+For the requests to succeed, you'll need to provide the service name and api-key as collection variables.
 
-```http
-api-key: <YOUR-AZURE-SEARCH-ADMIN-API-KEY>
-Content-Type: application/json
-```
+1. Open the Postman Desktop app and import the collection.
 
-In Postman, formulate a request that looks like the following screenshot. Choose **GET** as the command, provide the URL, and click **Send**. This command connects to Azure Cognitive Search, reads the indexes collection, and returns HTTP status code 200 on a successful connection. If your service has indexes already, the response will also include index definitions.
+1. Select the collection's access menu, select **Edit**, and provide the service name and key of your search service.
 
-![Postman request URL and header](media/search-get-started-rest/postman-url.png "Postman request URL and header")
+   :::image type="content" source="media/search-get-started-rest/postman-collection-variables.png" lightbox="media/search-get-started-rest/postman-collection-variables.png"alt-text="Screenshot of the Postman collection variable page." border="true":::
 
 ## 1 - Create an index
 
 In Azure Cognitive Search, you usually create the index before loading it with data. The [Create Index REST API](/rest/api/searchservice/create-index) is used for this task. 
 
-The URL is extended to include the `hotels` index name.
+The URL is extended to include the `hotels-quickstart` index name.
 
-To do this in Postman:
+1. Set the verb to **PUT**.
 
-1. Change the command to **PUT**.
+2. Copy in this URL `https://{{service-name}}.search.windows.net/indexes/hotels-quickstart?api-version=2020-06-30`.
 
-2. Copy in this URL `https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart?api-version=2020-06-30`.
+3. Provide the index definition (copy-ready code is provided next) in the body of the request.
 
-3. Provide the index definition (copy-ready code is provided below) in the body of the request.
-
-4. Click **Send**.
+4. Select **Send**.
 
 ![Index JSON document in request body](media/search-get-started-rest/postman-request.png "Index JSON document in request body")
 
 ### Index definition
 
-The fields collection defines document structure. Each document must have these fields, and each field must have a data type. String fields are used in full text search. If you need numeric data to be searchable, you will need to cast numeric data as strings.
+The fields collection defines document structure. Each document must have these fields, and each field must have a data type. String fields are used in full text search. If you need numeric data to be searchable, you'll need to cast numeric data as strings.
 
 Attributes on the field determine allowed action. The REST APIs allow many actions by default. For example, all strings are searchable, retrievable, filterable, and facetable by default. Often, you only have to set attributes when you need to turn off a behavior.
 
@@ -122,15 +117,13 @@ Creating the index and populating the index are separate steps. In Azure Cogniti
 
 The URL is extended to include the `docs` collections and `index` operation.
 
-To do this in Postman:
-
-1. Change the command to **POST**.
+1. Set the verb to **POST**.
 
-2. Copy in this URL `https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2020-06-30`.
+2. Copy in this URL `https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2020-06-30`.
 
-3. Provide the JSON documents (copy-ready code is below) in the body of the request.
+3. Provide the JSON documents (copy-ready code is next) in the body of the request.
 
-4. Click **Send**.
+4. Select **Send**.
 
 ![JSON documents in request body](media/search-get-started-rest/postman-docs.png "JSON documents in request body")
 
@@ -225,54 +218,50 @@ In a few seconds, you should see an HTTP 201 response in the session list. This
 
 If you get a 207, at least one document failed to upload. If you get a 404, you have a syntax error in either the header or body of the request: verify you changed the endpoint to include `/docs/index`.
 
-> [!Tip]
+> [!TIP]
 > For selected data sources, you can choose the alternative *indexer* approach which simplifies and reduces the amount of code required for indexing. For more information, see [Indexer operations](/rest/api/searchservice/indexer-operations).
 
-
 ## 3 - Search an index
 
 Now that an index and document set are loaded, you can issue queries against them using [Search Documents REST API](/rest/api/searchservice/search-documents).
 
 The URL is extended to include a query expression, specified using the search operator.
 
-To do this in Postman:
-
-1. Change the command to **GET**.
+1. Set the verb to **GET**.
 
-2. Copy in this URL `https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2020-06-30`.
+2. Copy in this URL `https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2020-06-30`.
 
-3. Click **Send**.
+3. Select **Send**.
 
-This query is an empty and returns a count of the documents in the search results. The request and response should look similar to the following screenshot for Postman after you click **Send**. The status code should be 200.
+This query is an empty and returns a count of the documents in the search results. The request and response should look similar to the following screenshot for Postman after you select **Send**. The status code should be 200.
 
  ![GET with search string on the URL](media/search-get-started-rest/postman-query.png "GET with search string on the URL")
 
 Try a few other query examples to get a feel for the syntax. You can do a string search, verbatim $filter queries, limit the results set, scope the search to specific fields, and more.
 
-Swap out the current URL with the ones below, clicking **Send** each time to view the results.
 
 ```
 # Query example 1 - Search on restaurant and wifi
 # Return only the HotelName, Description, and Tags fields
-https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?search=restaurant wifi&$count=true&$select=HotelName,Description,Tags&api-version=2020-06-30
+https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=restaurant wifi&$count=true&$select=HotelName,Description,Tags&api-version=2020-06-30
 
 # Query example 2 - Apply a filter to the index to find hotels rated 4 or highter
 # Returns the HotelName and Rating. Two documents match
-https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?search=*&$filter=Rating gt 4&$select=HotelName,Rating&api-version=2020-06-30
+https://{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=*&$filter=Rating gt 4&$select=HotelName,Rating&api-version=2020-06-30
 
 # Query example 3 - Take the top two results, and show only HotelName and Category in the results
-https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?search=boutique&$top=2&$select=HotelName,Category&api-version=2020-06-30
+https://{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=boutique&$top=2&$select=HotelName,Category&api-version=2020-06-30
 
 # Query example 4 - Sort by a specific field (Address/City) in ascending order
-https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating&api-version=2020-06-30
+https://{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating&api-version=2020-06-30
 ```
 
 ## Get index properties
 
 You can also use [Get Statistics](/rest/api/searchservice/get-index-statistics) to query for document counts and index size: 
 
 ```http
-https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/stats?api-version=2020-06-30
+https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/stats?api-version=2020-06-30
 ```
 
 Adding `/stats` to your URL returns index information. In Postman, your request should look similar to the following, and the response includes a document count and space used in bytes.
@@ -287,11 +276,11 @@ When you're working in your own subscription, it's a good idea at the end of a p
 
 You can find and manage resources in the portal, using the **All resources** or **Resource groups** link in the left-navigation pane.
 
-If you are using a free service, remember that you are limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit. 
+If you're using a free service, remember that you're limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit. 
 
 ## Next steps
 
-Now that you know how to perform core tasks, you can move forward with additional REST API calls for more advanced features, such as indexers or [setting up an enrichment pipeline](cognitive-search-tutorial-blob.md) that adds content transformations to indexing. For your next step, we recommend the following link:
+Now that you know how to perform core tasks, you can move forward with more REST API calls for advanced features, such as indexers or [setting up an enrichment pipeline](cognitive-search-tutorial-blob.md) that adds content transformations to indexing. For your next step, we recommend the following link:
 
 > [!div class="nextstepaction"]
 > [Tutorial: Use REST and AI to generate searchable content from Azure blobs](cognitive-search-tutorial-blob.md)