// We recommend including "api" in the page ID and title for improved SEO.
[[sample-api]]
=== Sample API
++++
<titleabbrev>Sample</titleabbrev>
++++
////
This section includes a brief, 1-2 sentence description
followed by an optional request example. DO NOT include the response.

While optional, we recommend including the example request when possible.
////

Creates a cool thing.

[source,console]
--------------------------------------------------
PUT twitter
--------------------------------------------------

////
***********************************************************
////

////
Use the appropriate heading levels for your book.
Add anchors for each section.
FYI: The section titles use attributes in case those terms change.
////

[[sample-api-request]]
==== {api-request-title}
////
This section show the basic endpoint, without the body or optional parameters.
Variables should use <...> syntax.
If an API supports both PUT and POST, include both here.
////

`PUT /<follower_index>/_ccr/follow`


[[sample-api-prereqs]]
==== {api-prereq-title}
////
Optional list of prerequisites.

For example:

* A snapshot of an index created in 5.x can be restored to 6.x. You must...
* If the {es} {security-features} are enabled, you must have `write`, `monitor`,
and `manage_follow_index` index privileges...
////


[[sample-api-desc]]
==== {api-description-title}
////
Add a more detailed description the context.
Link to related APIs if appropriate.
////

////
Guidelines for parameter documentation
***************************************
* Use a definition list.
* End each definition with a period.
* Include whether the parameter is Optional or Required and the data type.
* Include default values as the last sentence of the first paragraph.
* Include a range of valid values, if applicable.
* If the parameter requires a specific delimiter for multiple values, say so.
* If the parameter supports wildcards, ditto.
***************************************
////
[[sample-api-path-params]]
==== {api-path-parms-title}
////
A list of all the parameters within the path of the endpoint (before the query string (?)).

For example:
`<follower_index>`::
(Required, string) Name of the follower index
////


[[sample-api-query-params]]
==== {api-query-parms-title}
////
A list of the parameters in the query string of the endpoint (after the ?).

For example:
`wait_for_active_shards`::
(Optional, integer) Specifies the number of shards to wait on being active before
responding. A shard must be restored from the leader index being active.
Restoring a follower shard requires transferring all the remote Lucene segment
files to the follower index. The default is `0`, which means waiting on none of
the shards to be active.
////

////
Guidelines for request and response body documentation
***************************************
* For large or nested objects, consider linking to a separate definition list
or using a collapsible section. For example, see the "get node stats" API or the
"create anomaly detection jobs" API.
***************************************
////
[role="child_attributes"]
[[sample-api-request-body]]
==== {api-request-body-title}
////
A list of the properties you can specify in the body of the request.

For example:
`remote_cluster`::
(Required, string) The <<modules-remote-clusters,remote cluster>> that contains
the leader index.

`leader_index`::
(Required, string) The name of the index in the leader cluster to follow.

////

[role="child_attributes"]
[[sample-api-response-body]]
==== {api-response-body-title}
////
Response body is only required for detailed responses.

For example:
`auto_follow_stats`::
  (object) An object representing stats for the auto-follow coordinator. This
  object consists of the following fields:

`auto_follow_stats.number_of_successful_follow_indices`:::
  (long) the number of indices that the auto-follow coordinator successfully
  followed
...

////


[[sample-api-response-codes]]
==== {api-response-codes-title}
////
Response codes are only required when needed to understand the response body.

For example:
`200`::
Indicates all listed indices or index aliases exist.

 `404`::
Indicates one or more listed indices or index aliases **do not** exist.
////


[[sample-api-example]]
==== {api-examples-title}
////
Optional additional examples.
DO NOT repeat the basic example used earlier.


[source,console]
----
PUT /follower_index/_ccr/follow?wait_for_active_shards=1
{
  "remote_cluster" : "remote_cluster",
  "leader_index" : "leader_index",
  "max_read_request_operation_count" : 1024,
  "max_outstanding_read_requests" : 16,
  "max_read_request_size" : "1024k",
  "max_write_request_operation_count" : 32768,
  "max_write_request_size" : "16k",
  "max_outstanding_write_requests" : 8,
  "max_write_buffer_count" : 512,
  "max_write_buffer_size" : "512k",
  "max_retry_delay" : "10s",
  "read_poll_timeout" : "30s"
}
----
// TEST[setup:remote_cluster_and_leader_index]

The API returns the following result:

[source,console-result]
----
{
  "follow_index_created" : true,
  "follow_index_shards_acked" : true,
  "index_following_started" : true
}
----
////