Yandex Cloud
Search
Contact UsGet started
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • AI Studio
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
    • Yandex Cloud Partner program
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
© 2025 Direct Cursus Technology L.L.C.
Yandex Cloud API concepts
  • Basic principles
    • Resource identification
    • Standard fields
  1. Resources
  2. Resource identification

Resource identification

Written by
Yandex Cloud
Updated at April 23, 2025

Each resource in the Yandex Cloud APIs has its own unique ID. IDs are generated on the service side. An ID is a string consisting of Latin letters and numbers.

IDs should be passed in API requests when accessing resources.

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

 rpc Get (GetDiskRequest) returns (Disk) {
   option (google.api.http) = {
     get: "/compute/v1/disks/{disk_id}"
   };
 }

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

In the REST API, each resource has its own unique URL generated according to the pattern:

https://<domain>/<service>/<API version>/<resource category>/<resource ID>

Sample REST request for a disk:

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

As you can see from the example, the resource URL is identified by the resource category and resource ID bundle.

The resource category determines the type of resource. For example, disks is a category of disks; instances is a category of VMs; and images is a category of images.

Note

A resource category should not be confused with the concept of collection in the REST API. Categories are not independent resources and you cannot manage them (create, change them, or request information). Categories are for service use, i.e., they are used in resource URLs for routing requests on the service side.

Nested resource IDsNested resource IDs

Some resources in APIs are nested, that is, created in the context of other resources. For example, databases are created in clusters. When accessing such resources, always specify the following two parameters:

  • ID of the parent resource. In the example with DBs, the parent resource is a cluster.
  • Nested resource name. In our example, the nested resource is a database.

The name of a nested resource is specified by the user and must be unique within the parent resource. For example, you cannot create two DBs with the same names in the same cluster.

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

 rpc Get (GetDatabaseRequest) returns (Database) {
   option (google.api.http) = {
     get: "/managed-postgresql/v1/clusters/{cluster_id}/databases/{database_name}"
   };
 }
 message GetDatabaseRequest {
   // ID of the cluster the DB belongs to.
   // Required field.
   string cluster_id = 1;

   // DB name.
   // Required field.
   string database_name = 2;
 }

The database_name field may contain up to 63 characters, including letters, numbers, underscores, and hyphens.

In the REST API, the unique URI of a nested resource has a hierarchical structure:

/<parent resource category>/<parent resource ID>/<nested resource category>/<nested resource ID>

Sample REST request for getting a DB:

 GET https://mdb.api.cloud.yandex.net/managed-postgresql/v1/clusters/24f17h0gfqf7oeuis2f/databases/db-testing

Where:

  • clusters: Parent resource category.
  • 24f17h0gfqf7oeuis2f: Parent resource ID.
  • databases: Nested resource category.
  • db-testing: Nested resource ID.

See alsoSee also

  • Yandex Cloud API repository: Link to the API .proto specifications.
  • Yandex Resource Manager documentation: Link to the Hierarchy of Yandex Cloud resources section.

Was the article helpful?

Previous
Basic principles
Next
Standard fields
© 2025 Direct Cursus Technology L.L.C.