Handle as Primary Identifier for APIs and Other Resources

[malinthaprasan]

Problem

Using UUIDs as URL Identifiers

Currently, UUIDs are used as identifiers in REST API URLs. This causes several issues:

1. URLs don't look nice: UUIDs like 550e8400-e29b-41d4-a716-446655440000 are not user-friendly or memorable.

2. Immutability limits flexibility: Users may want to rename or reorganize resources, but UUIDs cannot change. User-provided identifiers should be mutable.

3. Difficult lookup: Users cannot easily lookup resources using a human-readable identifier they provided.

4. Client integration complexity: External systems and API clients benefit from predictable, human-readable identifiers rather than opaque UUIDs.

Why Not Just Replace UUID with Handle?

We cannot simply replace the current UUID with a user-provided handle because:

• Handles can be changed by the user at any time
• All internal references (analytics, events, cross-system tracking) would become invalid on handle change
• We need an immutable identifier for internal correlation

The Three Identifier Problem

This leads to having three identifiers per resource:

1. id - Database auto-increment (internal only)
2. handle - User-provided identifier (external, mutable)
3. uuid - Auto-generated UUID (internal, immutable)

This raises questions about which identifier to use in each layer and how to handle conversions between them.

Solution

Adopt a handle-first approach where:

• Handles are the primary identifier for all external and service-layer operations
• UUIDs are secondary, used only for internal tracking and analytics
• Database IDs never leave the repository layer
• Clear naming conventions eliminate ambiguity (handle, uuid instead of id)

Types of Identifiers

There are three types of identifiers for each resource:

Type	Description	Scope	Mutability
id	Auto-generated integer ID	Database only	Immutable
uuid	Auto-generated UUID	Internal systems	Immutable
handle	User-provided or auto-generated URL-friendly identifier	External APIs	Mutable

1. ID (Integer)

• Auto-generated by the database
• Used exclusively at the database level
• Serves as the primary key and foreign key references in related tables
• Should never be exposed outside the repository layer

2. UUID

• Auto-generated UUID string
• Internal immutable identifier for the resource
• Used to identify resources across external systems
• Useful for analytics and event tracking where handle changes should not affect resource correlation

Example Use Case:
When API analytics data is published to an external system, events include both uuid and handle. Even if the handle changes later, the external system can still uniquely identify the API using the immutable UUID.

3. Handle

• User-provided or auto-generated URL-friendly identifier
• Externally exposed identifier used in REST API paths
• Mutable (can be changed by the user)
• Must be unique within the organization scope

Naming Conventions

REST API Layer

The {id} in URL paths is interpreted as the handle.

Resource Operations

POST   /resources                  # Create a new resource
GET    /resources                  # List all resources
GET    /resources/{id}             # Get a resource by handle
PUT    /resources/{id}             # Update a resource by handle
DELETE /resources/{id}             # Delete a resource by handle

Sub-Resource Operations

POST   /resources/{id}/sub-resources                  # Create a new sub-resource
GET    /resources/{id}/sub-resources                  # List all sub-resources
GET    /resources/{id}/sub-resources/{subResourceId}  # Get a sub-resource by handle
PUT    /resources/{id}/sub-resources/{subResourceId}  # Update a sub-resource by handle
DELETE /resources/{id}/sub-resources/{subResourceId}  # Delete a sub-resource by handle

Resource Model

{
  "id": "my-resource",
  "orgId": "my-org",
  "name": "My Resource"
}

Sub-Resource Model

{
  "id": "my-sub-resource",
  "resourceId": "my-resource",
  "orgId": "my-org",
  "name": "My Sub Resource"
}

Backend Code Conventions

From the service layer onwards, use explicit variable names to avoid confusion:

Avoid	Use Instead
id (ambiguous)	handle or uuid (explicit)
apiId	apiHandle or apiUUID
resourceId	resourceHandle or resourceUUID

Sample SQL Schema

CREATE TABLE organization (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    uuid VARCHAR(36) NOT NULL UNIQUE,
    handle VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(255) NOT NULL
);

CREATE TABLE resource (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    uuid VARCHAR(36) NOT NULL UNIQUE,
    handle VARCHAR(255) NOT NULL,
    org_id INTEGER NOT NULL REFERENCES organization(id),
    name VARCHAR(255) NOT NULL,
    -- other columns...
    UNIQUE(handle, org_id)
);

CREATE TABLE sub_resource (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    uuid VARCHAR(36) NOT NULL UNIQUE,
    handle VARCHAR(255) NOT NULL,
    resource_id INTEGER NOT NULL REFERENCES resource(id),
    org_id INTEGER NOT NULL REFERENCES organization(id),
    name VARCHAR(255) NOT NULL,
    -- other columns...
    UNIQUE(handle, resource_id, org_id)
);

Layer-Specific Patterns

Repository Layer

The repository layer works with handles for resource identification:

CreateResource(resource *Resource) error
GetResource(handle, orgHandle string) (*Resource, error)
UpdateResource(handle, resource *Resource) error
DeleteResource(handle, orgHandle string) error

// Metadata lookup for UUID-to-handle conversion
GetResourceMetadataByUUID(uuid, orgUUID string) (*ResourceMetadata, error)

Service Layer

The service layer provides handle-based operations as the primary interface:

// Handle-based operations (core)
CreateResource(req *CreateRequest, orgHandle string) (*ResourceDTO, error)
GetResource(handle, orgHandle string) (*ResourceDTO, error)
UpdateResource(handle string, req *UpdateRequest, orgHandle string) (*ResourceDTO, error)
DeleteResource(handle, orgHandle string) error

// UUID-based operations (convenience wrappers)
GetResourceByUUID(uuid, orgUUID string) (*ResourceDTO, error)
UpdateResourceByUUID(uuid string, req *UpdateRequest, orgUUID string) (*ResourceDTO, error)
DeleteResourceByUUID(uuid, orgUUID string) error

Handle-Based Core Pattern

All primary operations use handles directly:

func (s *Service) GetResource(handle, orgHandle string) (*ResourceDTO, error) {
    resource, err := s.repo.GetResource(handle, orgHandle)
    if err != nil {
        return nil, err
    }
    return mapToDTO(resource), nil
}

func (s *Service) UpdateResource(handle string, req *UpdateRequest, orgHandle string) (*ResourceDTO, error) {
    resource, err := s.repo.GetResource(handle, orgHandle)
    if err != nil {
        return nil, err
    }
    // Apply updates
    applyUpdates(resource, req)
    err = s.repo.UpdateResource(resource)
    if err != nil {
        return nil, err
    }
    return mapToDTO(resource), nil
}

func (s *Service) DeleteResource(handle, orgHandle string) error {
    return s.repo.DeleteResource(handle, orgHandle)
}

UUID-to-Handle Resolution Pattern

UUID-based service methods should resolve the UUID to handle once, then delegate to handle-based methods:

func (s *Service) GetResourceByUUID(uuid, orgUUID string) (*ResourceDTO, error) {
    // Do the conversion once
    resourceMetadata, err := s.repo.GetResourceMetadataByUUID(uuid, orgUUID)
    if err != nil {
        return nil, err
    }
    return s.GetResource(resourceMetadata.Handle, resourceMetadata.OrgHandle)
}

func (s *Service) UpdateResourceByUUID(uuid string, req *UpdateRequest, orgUUID string) (*ResourceDTO, error) {
    resourceMetadata, err := s.repo.GetResourceMetadataByUUID(uuid, orgUUID)
    if err != nil {
        return nil, err
    }
    return s.UpdateResource(resourceMetadata.Handle, req, resourceMetadata.OrgHandle)
}

func (s *Service) DeleteResourceByUUID(uuid, orgUUID string) error {
    resourceMetadata, err := s.repo.GetResourceMetadataByUUID(uuid, orgUUID)
    if err != nil {
        return err
    }
    return s.DeleteResource(resourceMetadata.Handle, resourceMetadata.OrgHandle)
}

Sub-Resource Operations

For sub-resources, the same pattern applies. Handle-based operations are core, UUID-based operations resolve to handles first.

Repository Layer

GetSubResource(handle, parentResourceHandle, orgHandle string) (*SubResource, error)

// Metadata lookups for UUID-to-handle conversion
GetSubResourceMetadataByUUID(uuid, parentResourceUUID, orgUUID string) (*SubResourceMetadata, error)

Service Layer

// Handle-based operations (core)
GetSubResource(handle, parentResourceHandle, orgHandle string) (*SubResourceDTO, error)

// UUID-based operations (convenience wrappers)
GetSubResourceByUUID(uuid, parentResourceUUID, orgUUID string) (*SubResourceDTO, error)

Handle-Based Core Pattern

func (s *Service) GetSubResource(handle, parentResourceHandle, orgHandle string) (*SubResourceDTO, error) {
    subResource, err := s.repo.GetSubResource(handle, parentResourceHandle, orgHandle)
    if err != nil {
        return nil, err
    }
    return mapToSubResourceDTO(subResource), nil
}

UUID-to-Handle Resolution Pattern

func (s *Service) GetSubResourceByUUID(uuid, parentResourceUUID, orgUUID string) (*SubResourceDTO, error) {
    // Do the conversion once
    subResourceMetadata, err := s.repo.GetSubResourceMetadataByUUID(uuid, parentResourceUUID, orgUUID)
    if err != nil {
        return nil, err
    }
    return s.GetSubResource(subResourceMetadata.Handle, subResourceMetadata.ParentResourceHandle, subResourceMetadata.OrgHandle)
}

[nuwand]

Why do we need an ID and UUID both? Both the ID and UUID are system generated and uneditable, so they are very similar.

In general, we will use the handle to access resources through our API. So there doesn't seem be to be enough justification to maintain both an ID and a UUID.