update rest api docs, fix links (#1074)

PSeitz · web-flow · commit e4fee7f00bdc · 2022-01-11T10:06:12.000+01:00
* update rest api docs

fix links
rename index name to index id

* fix headings

* fix gh link in quickwit config

* fix query language link

* fix caution block
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -213,7 +213,7 @@ quickwit index search
 
 `--index` ID of the target index.    
 `--config` Quickwit config file.    
-`--query` Query expressed in natural query language (barack AND obama) OR "president of united states"). Learn more on https://quickwit.io/docs/reference/search-language.    
+`--query` Query expressed in natural query language (barack AND obama) OR "president of united states"). Learn more on [query language](./query-language)     
 `--max-hits` Maximum number of hits returned. (Default: 20)    
 `--start-offset` Offset in the global result set of the first hit returned. (Default: 0)    
 `--search-fields` List of fields that Quickwit will search into if the user query does not explicitly target a field in the query. It overrides the default search fields defined in the index config. Space-separated list, e.g. "field1 field2".    
diff --git a/docs/reference/index-config.md b/docs/reference/index-config.md
@@ -74,10 +74,12 @@ The `index-uri` parameter is optional.
 By default, the `index-uri` will be computed by concatenating the `index-id` with the
 `default_index_root_uri` defined in the [Quickwit's config](quickwit-config).
 
-<aside>
-⚠️ The file storage will not work when running quickwit in distributed mode.
+
+:::caution
+The file storage will not work when running quickwit in distributed mode.
 Today, only the s3 storage is available when running several searcher nodes.
-</aside>
+:::
+
 
 ## Doc mapping
 
diff --git a/docs/reference/quickwit-config.md b/docs/reference/quickwit-config.md
@@ -9,7 +9,7 @@ This page documents the Quickwit configuration properties. It is divided into th
 - Indexer properties: defined in `[indexer]` section of the configuration file.
 - Searcher properties: defined in `[searcher]` section of the configuration file.
 
-A commented example is accessible here: [quickwit.yaml]([link](https://github.com/quickwit-inc/quickwit/blob/main/config/quickwit.yaml)).
+A commented example is accessible here: [quickwit.yaml](https://github.com/quickwit-inc/quickwit/blob/d9c4fda658baa3bd7291f8abdff8c4b4b56c232f/config/quickwit.yaml).
 
 ## Common configuration
 
@@ -42,4 +42,4 @@ This section contains the configuration options for a Searcher.
 | --- | --- | --- |
 | fast_field_cache_capacity | Fast field cache capacity on a Searcher. | 10G |
 | split_footer_cache_capacity | Split footer cache (it is essentially the hotcache) capacity on a Searcher. | 1G |
-| max_num_concurrent_split_streams | Maximum number of concurrent split stream requests running on a Searcher. | 100 |
+| max_num_concurrent_split_streams | Maximum number of concurrent split stream requests running on a Searcher. | 100 |
diff --git a/docs/reference/rest-api.md b/docs/reference/rest-api.md
@@ -13,17 +13,17 @@ All the API endpoints start with the `api/v1/` prefix. `v1` indicates that we ar
 The API uses **JSON** encoded as **UTF-8**. The body of POST and PUT requests must be a JSON object and their `Content-Type` header should be set to `application/json; charset=UTF-8`.
 
 The response for the /search endpoint is always a JSON object, and the content type is always `application/json; charset=UTF-8.`
-The response for the /search/stream endpoint is a HTTP stream. Depending on the client capability it is a HTTP1.1 (chunked transfer encoded stream)[https://en.wikipedia.org/wiki/Chunked_transfer_encoding] or a HTTP2 stream.
+The response for the /search/stream endpoint is a HTTP stream. Depending on the client capability it is a HTTP1.1 [chunked transfer encoded stream](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) or a HTTP2 stream.
 
-## Parameters
+### Parameters
 
 Parameters passed in the URL must be properly URL-encoded, using the UTF-8 encoding for non-ASCII characters.
 
 ```
 GET [..]/search?query=barack%20obama
 ```
 
-## Error handling
+### Error handling
 
 Successful requests return a 2xx HTTP status code.
 
@@ -40,16 +40,16 @@ Failed requests return a 4xx HTTP status code. The response body of failed reque
 ### Search in an index
 
 ```
-GET api/v1/indexes/<index name>/search
+GET api/v1/indexes/<index id>/search
 ```
 
-Search for documents matching a query in the given index `<index name>`.
+Search for documents matching a query in the given index `<index id>`.
 
 #### Path variable
 
 | Variable      | Description   |
 | ------------- | ------------- |
-| **index name** | The index name |
+| **index id** | The index id |
 
 
 #### Get parameters
@@ -65,7 +65,7 @@ Search for documents matching a query in the given index `<index name>`.
 | **format**                 | `Enum`           	| The output format. Allowed values are "json" or "prettyjson" 						 | `prettyjson`                                                                                            |
 
 
-### Response
+#### Response
 
 | Field                | Description                    |    Type    |
 | -------------------- | ------------------------------ | :--------: |
@@ -76,10 +76,10 @@ Search for documents matching a query in the given index `<index name>`.
 ### Search stream in an index
 
 ```
-GET api/v1/indexes/<index name>/search/stream
+GET api/v1/indexes/<index id>/search/stream
 ```
 
-Streams field values from ALL documents matching a search query in the given index `<index name>`, in a specified output format among the following:
+Streams field values from ALL documents matching a search query in the given index `<index id>`, in a specified output format among the following:
  -  [CSV](https://datatracker.ietf.org/doc/html/rfc4180)
  -  [ClickHouse RowBinary](https://clickhouse.tech/docs/en/interfaces/formats/#rowbinary)
 
@@ -94,7 +94,7 @@ The endpoint will return 10 million values if 10 million documents match the que
 
 | Variable      | Description   |
 | ------------- | ------------- |
-| **index name** | The index name |
+| **index id** | The index id |
 
 
 #### Get parameters
@@ -109,11 +109,11 @@ The endpoint will return 10 million values if 10 million documents match the que
 | **outputFormat** | `String` | Response output format. `csv` or `clickHouseRowBinary`  | `csv` |
 
 
-### Response
-The response is an HTTP stream. Depending on the client's capability, it is an HTTP1.1 (chunked transfer encoded stream)[https://en.wikipedia.org/wiki/Chunked_transfer_encoding] or an HTTP2 stream.
+#### Response
+The response is an HTTP stream. Depending on the client's capability, it is an HTTP1.1 [chunked transfer encoded stream](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) or an HTTP2 stream.
 
 It returns a list of all the field values from documents matching the query. The field must be marked as "fast" in the index config for this to work. 
 The formatting is based on the specified output format. 
 
-On error, an "X-Stream-Error" header will be sent via the trailers channel with information about the error, and the stream will be closed via (`sender.abort()`)[https://docs.rs/hyper/latest/hyper/body/struct.Sender.html#method.abort].
+On error, an "X-Stream-Error" header will be sent via the trailers channel with information about the error, and the stream will be closed via [`sender.abort()`](https://docs.rs/hyper/0.14.16/hyper/body/struct.Sender.html#method.abort).
 Depending on the client, the trailer header with error details may not be shown. The error will also be logged in quickwit ("Error when streaming search results"). 
