API view, update, and delete operations typically target a single resource per request. Resources can be identified either
By ID, or
By name + parent identifier(s)
Parent identifiers are needed when the name alone is not enough to uniquely determine a resource. IDs are v4 UUIDs and therefore globally unique. Names, however, are only unique within a parent container (e.g., instance names within a project, subnet names within a VPC).
Example: Project
Projects are a top-level resource, so a name is sufficient to uniquely determine a project. Either of these will work to fetch a project:
/v1/projects/<project ID>/v1/projects/<project name>
Example: Disk in Project
Every disk is contained in a parent project. Any of the following will work to specify the disk:
(disk ID)(disk name, project ID)(disk name, project name)
The resource’s own name or ID is included in the path, while parent identifiers go in query params. The corresponding URIs for a GET request for that disk would be:
/v1/disks/<disk ID>/v1/disks/<disk name>?project=<project ID>/v1/disks/<disk name>?project=<project name>
Example: Subnet in VPC in Project
The above logic extends to resources that are nested further. VPC subnets have a parent VPC, and VPCs have a parent project. Any of the following will work to specify a subnet:
(subnet ID)(subnet name, VPC ID)(subnet name, VPC name, project ID)(subnet name, VPC name, project name)
The corresponding URIs for a GET request for that subnet would be:
/v1/vpc-subnets/<subnet ID>/v1/vpc-subnets/<subnet name>?vpc=<vpc ID>/v1/vpc-subnets/<subnet name>?vpc=<vpc name>&project=<project ID>/v1/vpc-subnets/<subnet name>?vpc=<vpc name>&project=<project name>