Updated on 2023-11-09 GMT+08:00

Listing Template Versions

Function

ListTemplateVersions

This API lists all template versions in a template.

  • By default, the template versions are sorted by creation time. The template created latest is displayed on the top.
  • Currently, all template versions are returned. Pagination is not supported.
  • If there is no template version, an empty list will be returned.
  • template_id is the unique ID of the template. It is a UUID generated by RFS when a template is created. Template names are unique at one specific time, so you can create a template named HelloWorld and another template with the same name after deleting the first one. For parallel development, team members may want to ensure that they are operating the template they created, not one with the same name created by other members after deleting the previous one. To avoid this mismatch, check the ID, since RFS ensures each template has a unique ID that does not change with updates. If the template_id value differs from the current template ID, 400 is returned.
  • If the template does not exist, 404 is returned.

ListTemplateVersions returns only summaries of template versions. For details, refer to ListTemplateVersionsResponseBody. To obtain the template version, call ShowTemplateVersionContent.

URI

GET /v1/{project_id}/templates/{template_name}/versions

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. It can be obtained by calling an API or from the console.

Obtaining a Project ID

Minimum: 3

Maximum: 64

template_name

Yes

String

Name of the template to be created.

Minimum: 1

Maximum: 128

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

template_id

No

String

ID of a template. If template_id exists, the template service checks whether template_id matches template_name. If not, 400 is returned.

Minimum: 36

Maximum: 36

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

Client-Request-Id

Yes

String

Unique request ID. It is specified by a user and is used to locate a request. UUID is recommended.

Minimum: 36

Maximum: 128

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

versions

Array of TemplateVersion objects

Template version list.

Array Length: 0 - 100

Table 5 TemplateVersion

Parameter

Type

Description

template_id

String

Unique template ID. It is randomly generated by the template service.

Minimum: 36

Maximum: 36

template_name

String

Name of the template to be created.

Minimum: 1

Maximum: 128

version_description

String

Description of a template version. It can be used by users to identify their own template versions.

Minimum: 0

Maximum: 1024

create_time

String

Creation time of a template version. The format complies with RFC3339 (YYYY-MM-DDTHH:MM:SSZ), for example, 1970-01-01T00:00:00Z.

version_id

String

Template version ID.

Minimum: 2

Maximum: 11

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 401

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 403

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 404

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 429

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 11 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Requests

  • List all versions of the current template.
    GET https://{endpoint}/v1/c364070ab35041ddae68cf8b4839b60f/templates/my_template/versions
  • List all versions of the current template and check whether the template ID matches the current template.
    GET https://{endpoint}/v1/c364070ab35041ddae68cf8b4839b60f/templates/my_template/versions?template_id=1b15e005-bdbb-4bd7-8f9a-a09b6774b4b3

Example Responses

Status code: 200

Template versions listed.

{
  "versions" : [ {
    "template_id" : "69f8d5ea-eaa4-4a3b-a96d-bae9230e97c8",
    "template_name" : "my_first_template",
    "version_description" : "Second version of the current template",
    "create_time" : "2023-05-09T08:01:24Z",
    "version_id" : "V2"
  }, {
    "template_id" : "69f8d5ea-eaa4-4a3b-a96d-bae9230e97c8",
    "template_name" : "my_first_template",
    "version_description" : "First version of the current template",
    "create_time" : "2023-05-09T08:01:23Z",
    "version_id" : "V1"
  } ]
}

Status Codes

Status Code

Description

200

Template versions listed.

400

Invalid request.

401

Authentication failed.

403

The user does not have the permission to call this API.

404

The template does not exist.

429

Too frequent requests.

500

Internal server error.

Error Codes

See Error Codes.