Standard methods

Written by

Updated at December 15, 2023

Get
List
Create
Update
Delete

Below, you can find a list of standard API methods and the respective HTTP methods:

API method	HTTP method	Request body	Response body
Get	GET	N/A	Resource view.
List	GET	N/A	List of resources.
Create	POST	Resource view.	Operation object.
Update	PATCH	Resource view.	Operation object.
Delete	DELETE	N/A	Operation object.

Below are gRPC descriptions of standard methods and examples of corresponding REST requests.

Get

Returns a view of the requested resource.

The corresponding HTTP method is GET.

Sample gRPC description of the Get method used to get a disk:

 rpc Get (GetDiskRequest) returns (Disk) {
   // The Get method corresponds to the HTTP GET method.
   option (google.api.http) = {
     get: "/compute/v1/disks/{disk_id}"
   };
 }

 message GetDiskRequest {
   // ID of the requested disk.
   string disk_id = 1;
 }

Sample REST request used to get a disk:

GET https://compute.api.cloud.yandex.net/compute/v1/disks/e0m97h0gbq0foeuis03

List

Returns a list of resources of a certain category. For example, a list of disks or VMs.

Currently, resource lists can only be obtained relative to their direct parent. For example, you can get a list of disks in a folder, but you can't view a list of disks in the entire cloud.

The List method corresponds to the HTTP GET method. The ID of the parent resource, such as the folder, should be passed in the request parameters.

The maximum page_size field value is 1000.

The List method supports result pagination.

Sample gRPC description of the List method used to get a list of disks:

 rpc List (ListDisksRequest) returns (ListDisksResponse) {
   // The List method corresponds to the HTTP GET method.
   option (google.api.http) = {
     get: "/compute/v1/disks"
   };
 }
 message ListDisksRequest {
   // ID of the folder for which
   // the list of disks is requested.
   // Required field.
   string folder_id = 1;

   // Maximum number of results per response page.
   // If the number of results returned
   // exceeds the value set in page_size, the service returns the field
   // [ListDisksResponse.next_page_token]. Use it to
   // get the next page.
   int64 page_size = 2;

   // Token of the requested result page.
   // To get the next page,
   // insert in this field the value from
   // [ListDisksResponse.next_page_token]
   // returned by the previous List request.
   string page_token = 3;
 }

 message ListDisksResponse {
   // List of disks.
   repeated Disk disks = 1;
   // Token for the next result page.
   string next_page_token = 2;
 }

Example of getting a list of disks in the REST API:

GET https://compute.api.cloud.yandex.net/compute/v1/disks?folderId=a3s17h9sbq5asdgss12

Create

Creates a resource in the specified cloud, folder, network, etc.

The Create method corresponds to the HTTP POST method. As parameters, pass the ID of the parent resource to create the new resource in (for example, the folder ID).

Create is an asynchronous signature method. It returns the Operation object with the operation status and the ID of the new resource.

The description field may contain up to 256 characters, while the name and labels field values may be up to 63 characters long.

If you try to create a resource that already exists, the method returns the ALREADY_EXISTS error. Learn more about errors

Sample gRPC description of the Create method used to create a disk in a specific folder:

 rpc Create (CreateDiskRequest) returns (operation.Operation) {
   // The Create method corresponds to the HTTP POST method.
   option (google.api.http) = {
     post: "/compute/v1/disks" body: "*"
   };
   // In the `metadata` field of the Operation object,
   // there is a `CreateDiskMetadata` view.
   // If the operation is successful,
   // the `response` field of the Operation object
   // contains a disk resource view.
   option (yandex.api.operation) = {
     metadata: "CreateDiskMetadata"
     response: "Disk"
   };
 }

 message CreateDiskRequest {
   // ID of the folder where the disk should be created.
   // Required field.
   string folder_id = 1;

   // Disk name.
   string name = 2;

   // Disk description.
   string description = 3;

   // Disk labels in 'key: value' format.
   map<string, string> labels = 4;

   // Disk type.
   string type_id = 5;

   // ID of the zone to create the disk in.
   string zone_id = 6;

   // Disk size in bytes.
   int64 size = 7;

   oneof source {
     // ID of the image to create the disk from.
     string image_id = 8;

     // or ID of the snapshot to create the disk from.
     string snapshot_id = 9;
   }
 }

 message CreateDiskMetadata {
   // ID of the disk being created.
   string disk_id = 1;
 }

Sample REST request used to create a disk:

 POST https://compute.api.cloud.yandex.net/compute/v1/disks

 {
   "folderId": "a3s17h9sbq5asdgss12",
   "name": "disk-1",
   "description": "Test disk",
   "zoneId" : "ru-central1-a",
   "typeId" : "network-nvme",
   "size" : 10737418240
 }

When calling the Create method, the returned Operation object will contain the ID of the resource being created, even if the operation is not complete yet. Using this ID, you can access the resource via the Get or List method.

Update

Updates a resource view. The method corresponds to the HTTP PATCH method.

The Update method supports partial resource updates. The fields to update are specified in the request's update_mask field (learn more). The fields not specified in the update_mask field will not be updated. If no update_mask is passed in the request, the values of all fields will be updated according to the following rule:

The passed values will be used for the fields specified in the request.
The values of the other fields will be reset to their defaults.

It is an asynchronous signature method. It returns the Operation object that contains the operation status and the view of the updated resource.

The description field may contain up to 256 characters, while the name and labels field values may be up to 63 characters long.

Sample gRPC description of the Update method used to update a disk resource:

 rpc Update (UpdateDiskRequest) returns (operation.Operation) {
   // The Update method corresponds to the HTTP PATCH method.
   option (google.api.http) = {
     patch: "/compute/v1/disks/{disk_id}" body: "*"
   };
   // In the `metadata` field of the Operation object,
   // there is an `UpdateDiskMetadata` view.
   // If the operation is successful,
   // the `response` field of the Operation object
   // contains a view of the updated disk resource.
   option (yandex.api.operation) = {
     metadata: "UpdateDiskMetadata"
     response: "Disk"
   };
 }
 message UpdateDiskRequest {
   // ID of the disk being updated.
   // Required field.
   string disk_id = 1;

   // Mask that sets the fields to update.
   google.protobuf.FieldMask update_mask = 2;

   // Disk name.
   string name = 3;

   // Disk description.
   string description = 4;

   // Disk labels in 'key: value' format.
   map<string, string> labels = 5;

   // Disk size in bytes.
   int64 size = 6;
 }

 message UpdateDiskMetadata {
   // ID of the disk being updated.
   string disk_id = 1;
 }

Sample REST request used to update a disk resource:

PATCH https://compute.api.cloud.yandex.net/compute/v1/disks/e0m97h0gbq0foeuis03

 {
   "name": "New name",
   "description": "New description",
   "size": "10737418240",
   "updateMask" : "name,description"
 }

In the example above, only the "name" and "description" fields will be updated.

Delete

Deletes the specified resource.

The Delete method corresponds to the HTTP DELETE method. In the request parameters, pass the ID of the resource to delete.

It is an asynchronous signature method. It returns the Operation object with the status of the deletion operation.

Sample gRPC description of the Delete method used to delete a disk:

 rpc Delete (DeleteDiskRequest) returns (operation.Operation) {
   // The method corresponds to the HTTP DELETE method.
   option (google.api.http) = {
     delete: "/compute/v1/disks/{disk_id}"
   };
   // In the `metadata` field of the Operation object,
   // there is a `DeleteDiskMetadata` view.
   // If the operation is successful,
   // the `response` field of the Operation object
   // contains a view of the `google.protobuf.Empty` resource.
   option (yandex.api.operation) = {
     metadata: "DeleteDiskMetadata"
     response: "google.protobuf.Empty"
   };
 }
 message DeleteDiskRequest {
   // ID of the disk to delete.
   // Required field.
   string disk_id = 1;
 }

 message DeleteDiskMetadata {
   // ID of the disk to delete.
   string disk_id = 1;
 }

Sample REST request used to delete a disk:

 DELETE https://compute.api.cloud.yandex.net/compute/v1/disks/e0m97h0gbq0foeuis03

Standard methods

GetGet

ListList

CreateCreate

UpdateUpdate

DeleteDelete

Was the article helpful?

Get

List

Create

Update

Delete