IN THIS ARTICLE
This article explains the deprecation of REST API endpoints for snapshots and policies, provides guidance for migrating from these endpoints to implementations on any version of Qumulo Core from 5.1.3 to 5.3.0, and explains minor changes in API behavior.
DETAILS
From Qumulo Core 5.1.3, multiple /v1/snapshots
and /v2/snapshots
are deprecated and marked for deletion in Qumulo Core 5.3.0. We replaced these REST API endpoints with /v2/snapshots/policies
and /v3/snapshots
endpoints that contain minor changes to API behavior and let you use policy snapshot naming. For more information about naming snapshot policies, see Taking Directory Snapshots on Demand or by Using a Snapshot Policy.
Migrating from /v1/snapshots/policies to /v2/snapshots/policies
The following table outlines the deprecated endpoints that you must rename.
Deprecated Endpoint | Replacement Endpoint |
GET /v1/snapshots/policies |
GET /v2/snapshots/policies |
POST /v1/snapshots/policies |
POST /v2/snapshots/policies |
GET /v1/snapshots/policies/<id> |
GET /v2/snapshots/policies/<id> |
PUT /v1/snapshots/policies/<id> |
PUT /v2/snapshots/policies/<id> |
PATCH /v1/snapshots/policies/<id> |
PATCH /v2/snapshots/policies/<id> |
DELETE /v1/snapshots/policies/<id> |
DELETE /v2/snapshots/policies/<id> |
- The
/v2/snapshots
endpoints return the following policy structure.{ "id": 1, "name": "policy", "snapshot_name_template": "{ID}_{Policy}", "schedule":{ ... }, "enabled": false, "source_file_id": "2" }
- The following are the changes in the policy structure:
- Added
snapshot_name_template
for naming snapshots. - Changed
source_file_ids
from a list to a singlesource_file_id
. - Changed
schedules
from a list to a singleschedule
. - Changed
name
topolicy_name
- Added
- The
POST
,PUT
, andPATCH
methods for the/v2/snapshots/policies
endpoints contain the following request body.{ "naming_pattern": "{ID}_{Policy}_{directory}", "enabled": true, "policy_name": policy, "schedule": { ... }, "source_file_id": 2 }
- The following are the changes in the policy creation request body:
- Added the
naming_pattern
field. - Removed the
id
andowners
inputs. - Changed
schedules
from a list to a singleschedule
. - Changed
source_file_ids
from a list to a singlesource_file_id
.
- Added the
Migrating from /v1/snapshots/policies/status to /v2/snapshots/policies/status
The following table outlines the deprecated endpoints that you must rename.
Deprecated Endpoint | Replacement Endpoint |
GET /v1/snapshots/policies/status |
GET /v2/snapshots/policies/status |
GET /v1/snapshots/policies/status/<id> |
GET /v2/snapshots/policies/status/<id> |
The /v2/snapshots/policies/status
endpoints return the following policy structure.
{ "id": 1, "policy_name": "policy", "snapshot_name_template": "{ID}_{Policy}", "schedule":{ ... }, "enabled": false, "source_file_id": 2, "source_file_path": "/", "owners": [] }
Migrating from /v1/snapshots and /v2/snapshots to /v3/snapshots
The following table outlines the deprecated endpoints that you must rename.
Deprecated Endpoint | Replacement Endpoint |
GET /v1/snapshots/ |
GET /v3/snapshots/ |
GET /v2/snapshots/ |
GET /v3/snapshots/ |
POST /v1/snapshots/ |
POST /v3/snapshots/ |
POST /v2/snapshots/ |
POST /v3/snapshots/ |
GET /v1/snapshots/<id> |
GET /v3/snapshots/<id> |
GET /v2/snapshots/<id> |
GET /v3/snapshots/<id> |
PUT /v1/snapshots/<id> |
PUT /v3/snapshots/<id> |
PUT /v2/snapshots/<id> |
PUT /v3/snapshots/<id> |
PATCH /v2/snapshots/<id> |
PATCH /v3/snapshots/<id> |
PATCH /v1/snapshots/<id> |
PATCH /v3/snapshots/<id> |
DELETE /v1/snapshots/<id> |
DELETE /v3/snapshots/<id> |
DELETE /v2/snapshots/<id> |
DELETE /v3/snapshots/<id> |
- The
GET /v3/snapshots
endpoints take thefilter
query parameter in the API request. Thefilter
flag lets you filter snapshots in process of being deleted and you can set it to one of the three following options.-
all
-
only_in_delete
-
exclude_in_delete
-
- The
/v3/snapshots
endpoints return the following policy structure.{ "id": "1", "name": "Some Unique Name", "timestamp": "2021-09-21T21:54:18.46936706Z", "policy_id": 1, "source_file_id": 2, "expiration": "", "in_delete": false }
- The following are changes in the snapshot structure:
- Removed the
directory_name
field. - Changed
create_by_policy
to an optionalpolicy_id
. - Changed
source_file_id
from a string to an integer.
- Removed the
- The
POST
,PUT
, andPATCH
/v3/snapshots
endpoints contain the following request body.{ "name_suffix": "any name", "source_file_id": 2, "expiration": "" }
- The following are the changes in the snapshot structure:
- Changed
name
tosuffix
. - Changed
source_file_id
from a string tofs_file_id
. - Removed
expiration_time_to_live
.
- Changed
Migrating from /v2/snapshots/statuses to /v3/snapshots/statuses
The following table outlines the deprecated endpoints that you must rename.
Deprecated Endpoint | Replacement Endpoint |
GET /v2/snapshots/statuses |
GET /v3/snapshots/statuses |
GET /v2/snapshots/statuses/<id> |
GET /v3/snapshots/statuses/<id> |
- The
/v3/snapshots/statuses
endpoints take thefilter
query parameter in the API request. Thefilter
flag lets you filter snapshots in process of being deleted and you can set it to one of the three following options.-
all
-
only_in_delete
-
exclude_in_delete
-
- The
/v3/snapshots/statuses
endpoints return the following policy status structure.{ "id": "1", "name": "Some Unique Name", "timestamp": "2021-09-21T21:54:18.46936706Z", "policy_id": 1, "policy_name": "my_policy", "source_file_id": 2, "source_file_path": "/", "expiration":, "owners": [], "in_delete": false }
Significant Changes in API Behavior
- The most important changes are in the
POST
andPUT
methods for the/v3/snapshots/policies
endpoint take thesnapshot_name_template
argument. This argument lets you name snapshots that you take by using a snapshot policy. - The corresponding
qq
CLI commands also accept the optional--snapshot-name-template
flag. Qumulo Core lets you pass in a naming template that serves as a foundation for all snapshots that you take from the policy.
The following table lists and explains the variables.
Note: All variables are case-insensitive.
Variable Name Description {Day}
The day on which Qumulo Core takes the snapshot. {Directory}
The name of the directory to snapshot. {Hour}
The hour in which Qumulo Core takes the snapshot. {ID]
The unique snapshot identifier that increases by one, starting from 1. {Minute}
The minute in which Qumulo Core takes the snapshot. {Month}
The month in which Qumulo Core takes the snapshot. {Policy}
The user-defined policy name. {Year}
The year in which Qumulo Core takes the snapshot. In addition to these variables, you can use any literals in the naming schema. You can also use
{{
and}}
for literals. Qumulo Core outputs these characters as{
and}
in the snapshot name.Notes:
- Don't use the slash (
/
) in policy names. - Qumulo Core truncates policy names more than 128 characters long.
- The default naming format for root directories is
{ID}_{Policy}
. - The default naming format for a directory snapshot is
{ID}_{Policy}_{Directory}
. - If two policies have the same name, Qumulo Core appends
_{ID}
to the name.
The following table shows examples of input snapshot naming templates and corresponding snapshot names.
Snapshot Naming Template Snapshot Name {Year}-{Month}-{Day}-{Policy}-my_text
2022-11-29-PolicyName-my_text
{Directory}-{Hour}-{Minute}-{ID}
MyDirectory-18-54-12345
{{{Year}-{Month}-{Hour}}}-{ID}
{2022-11-54}-12345
- Don't use the slash (
- This API change removes the
time-to-live
parameter that was previously passed into thePOST
method of the/v2/snapshots
endpoint and thePUT
andPATCH
methods for the/v2/snapshots/<id>
endpoints. Using theexpiration
flag is the only means to set the snapshot expiration time. - This API changes the ability to include and exclude snapshots in process of being deleted from a Boolean parameter to a filter parameter. The
GET
method for the/v3/snapshots
and/v3/snapshots/statuses
endpoints takes an optional query parameter that can exclude, include, or delete snapshots in process of being deleted.
Comments
0 comments