diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc index 56b5214d7a0..62624de05b6 100644 --- a/docs/reference/rest-api/index.asciidoc +++ b/docs/reference/rest-api/index.asciidoc @@ -33,6 +33,7 @@ endif::[] * <> * <> * <> +* <> * <> * <> * <> @@ -62,6 +63,7 @@ include::{es-repo-dir}/rollup/rollup-api.asciidoc[] include::{es-repo-dir}/search.asciidoc[] include::{es-repo-dir}/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc[] include::{xes-repo-dir}/rest-api/security.asciidoc[] +include::{es-repo-dir}/snapshot-restore/apis/snapshot-restore-apis.asciidoc[] include::{es-repo-dir}/slm/apis/slm-api.asciidoc[] include::{es-repo-dir}/transform/apis/index.asciidoc[] include::usage.asciidoc[] diff --git a/docs/reference/snapshot-restore/apis/clean-up-repo-api.asciidoc b/docs/reference/snapshot-restore/apis/clean-up-repo-api.asciidoc new file mode 100644 index 00000000000..4356403f65f --- /dev/null +++ b/docs/reference/snapshot-restore/apis/clean-up-repo-api.asciidoc @@ -0,0 +1,116 @@ +[[clean-up-snapshot-repo-api]] +=== Clean up snapshot repository API +++++ +Clean up snapshot repository +++++ + +Triggers the review of a snapshot repository's contents and deletes any stale +data that is not referenced by existing snapshots. + +//// +[source,console] +----------------------------------- +PUT /_snapshot/my_repository +{ + "type": "fs", + "settings": { + "location": "my_backup_location" + } +} +----------------------------------- +// TESTSETUP +//// + +[source,console] +---- +POST /_snapshot/my_repository/_cleanup +---- + +[[clean-up-snapshot-repo-api-request]] +==== {api-request-title} + +`POST /_snapshot//_cleanup` + +[[clean-up-snapshot-repo-api-desc]] +==== {api-description-title} + +Over time, snapshot repositories can accumulate stale data that is no longer +referenced by existing snapshots. + +While this unreferenced data does not negatively impact the performance or +safety of a snapshot repository, it can lead to more storage use than necessary. + +You can use the clean up snapshot repository API to detect and delete this +unreferenced data. + +[TIP] +==== +Most cleanup operations performed by this API are performed automatically when +a snapshot is deleted from a repository. + +If you regularly delete snapshots, calling this API may only reduce your storage +slightly or not at all. +==== + +[[clean-up-snapshot-repo-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Name of the snapshot repository to review and clean up. + +[[clean-up-snapshot-repo-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +[role="child_attributes"] +[[clean-up-snapshot-repo-api-response-body]] +==== {api-response-body-title} + +`results`:: +(object) +Contains statistics for cleanup operations. ++ +.Properties of `results` +[%collapsible%open] +==== +`deleted_bytes`:: +(integer) +Number of bytes freed by cleanup operations. + +`deleted_blobs`:: +(integer) +Number of binary large objects (blobs) removed from the snapshot repository +during cleanup operations. Any non-zero value implies that unreferenced blobs +were found and subsequently cleaned up. +==== + +[[clean-up-snapshot-repo-api-example]] +==== {api-examples-title} + +[source,console] +---- +POST /_snapshot/my_repository/_cleanup +---- + +The API returns the following response: + +[source,console-result] +---- +{ + "results": { + "deleted_bytes": 20, + "deleted_blobs": 5 + } +} +---- +// TEST[s/"deleted_bytes": 20/"deleted_bytes": 0/] +// TEST[s/"deleted_blobs": 5/"deleted_blobs": 0/] + +//// +[source,console] +---- +DELETE /_snapshot/my_repository +---- +//// \ No newline at end of file diff --git a/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc b/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc new file mode 100644 index 00000000000..f820fc5e096 --- /dev/null +++ b/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc @@ -0,0 +1,22 @@ +[[snapshot-restore-apis]] +== Snapshot and restore APIs + +You can use the following APIs to set up snapshot repositories, manage snapshot +backups, and restore snapshots to a running cluster. + +For more information, see <>. + +[NOTE] +==== +We are working on including more snapshot and restore APIs in this section. Some +content may not be included yet. +==== + +[discrete] +[[snapshot-restore-repo-apis]] +=== Snapshot repository management APIs + +* <> + + +include::clean-up-repo-api.asciidoc[] \ No newline at end of file diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json b/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json index ca4783368d1..727fe791767 100644 --- a/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json +++ b/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json @@ -1,7 +1,7 @@ { "snapshot.cleanup_repository": { "documentation": { - "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/clean-up-snapshot-repo-api.html", "description": "Removes stale data from repository." }, "stability": "stable",