Migrating REST API Endpoints for Snapshots and Policies

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.

• 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 single source_file_id.
  • Changed schedules from a list to a single schedule.
  • Changed name to policy_name
• The POST, PUT, and PATCH 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 and owners inputs.
  • Changed schedules from a list to a single schedule.
  • Changed source_file_ids from a list to a single source_file_id.

Migrating from /v1/snapshots/policies/status to /v2/snapshots/policies/status

The following table outlines the deprecated endpoints that you must rename.

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.

• The GET /v3/snapshots endpoints take the filter query parameter in the API request. The filter 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 optional policy_id.
  • Changed source_file_id from a string to an integer.
• The POST, PUT, and PATCH /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 to suffix.
  • Changed source_file_id from a string to fs_file_id.
  • Removed expiration_time_to_live.

Migrating from /v2/snapshots/statuses to /v3/snapshots/statuses

The following table outlines the deprecated endpoints that you must rename.

• The /v3/snapshots/statuses endpoints take the filter query parameter in the API request. The filter 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 and PUT methods for the /v3/snapshots/policies endpoint take the snapshot_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

• This API change removes the time-to-live parameter that was previously passed into the POST method of the /v2/snapshots endpoint and the PUT and PATCH methods for the /v2/snapshots/<id> endpoints. Using the expiration 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.