Skip to main content

ID-or-Name Resolution

Every resource in The Shift Platform has two identifiers:

  • ID -- an 8-character nanoid (e.g., abc12345), assigned at creation and immutable.
  • Name -- a human-readable string (e.g., auth-service), set by the user and unique within its collection.

All CLI commands and API endpoints accept either form interchangeably.

How It Works​

The resolveId() function handles the resolution:

  1. Check by ID first. Look up the given string as an exact ID match.
  2. Fall back to name. If no record has that ID, search by name (case-insensitive).
  3. Return as-is. If neither matches, return the input unchanged and let the caller handle the missing resource.
export function resolveId<T extends { id: string; name: string }>(
  root: string,
  collection: Collection,
  idOrName: string,
): string {
  const byId = readOne<T>(root, collection, idOrName);
  if (byId) return idOrName;

  const byName = findByName<T>(root, collection, idOrName);
  if (byName) return byName.id;

  return idOrName;
}

This same pattern is implemented across all services and in the Repository<T> interface from @shift/platform-core/storage:

interface Repository<T extends { id: string }> {
  getAll(): Promise<T[]>;
  getById(id: string): Promise<T | null>;
  findByName(name: string): Promise<T | null>;
  resolveId(idOrName: string): Promise<string>;
  save(record: T): Promise<void>;
  delete(id: string): Promise<boolean>;
}

CLI Examples​

Both of these commands refer to the same service:

# By name
$ shift-cli yp services get auth-service

# By ID
$ shift-cli yp services get abc12345

The same applies to any command that takes a resource identifier:

# Remove by name
$ shift-cli yp services rm my-old-service

# Show owner by ID
$ shift-cli yp owners show XkR9mP2q

# Get passport config by name
$ shift-cli passport configs get production

API Behavior​

API endpoints follow the same pattern. When an endpoint accepts :idOrName as a path parameter, it resolves using the same logic:

GET /api/v1/catalog/services/auth-service
GET /api/v1/catalog/services/abc12345

Both return the same service record.

Case Sensitivity​

  • IDs are case-sensitive (nanoid characters include both uppercase and lowercase).
  • Name lookups are case-insensitive: Auth-Service, auth-service, and AUTH-SERVICE all resolve to the same record.

Why This Pattern Exists​

AI agents and automated scripts benefit from using stable IDs that never change, even if a resource is renamed. Human operators benefit from using memorable names. By supporting both in every context, The Shift Platform avoids forcing a choice between machine-friendly and human-friendly interfaces.