Skip to main content

URL Hash Scheme

URL Hash Scheme Documentation​

This document outlines the URL hash scheme used in the application for referencing entities such as person, os_file, or vehicle. The scheme is designed to be flexible, intuitive, and easily extendable for future actions like editing or exporting entities.

Basic Structure​

The URL hash consists of several components:

  • Action (Optional): Specifies the action to be performed on the entity (e.g., edit, export, or no action, implying the default view action).
  • Entity ID: A unique identifier for the entity.
  • Entity Type (Optional): Specifies the type of the entity (person, os_file, vehicle).
  • Entity Label (Optional): A human-readable label that gives additional context or information about the entity.

Format​

#action/entity_id/entity_type#entity_label
  • Action: The action to be performed, such as edit or export. This is optional, and if omitted, the default action (e.g., viewing) is assumed.
  • Entity ID: A unique identifier that distinguishes the entity.
  • Entity Type: Specifies the type of the entity. This is optional but recommended for clarity.
  • Entity Label: An optional descriptive label for the entity, separated by a second hash (#).

Examples​

  1. Viewing a Person:
    • Format: #entity_id/entity_type#entity_label
    • Example: #550e8400-e29b-41d4-a716-446655440000/person#john-doe
    • Explanation: This URL points to a person entity with the ID 550e8400-e29b-41d4-a716-446655440000 and a label john-doe.
  2. Editing a Vehicle:
    • Format: #action/entity_id/entity_type#entity_label
    • Example: #edit/123e4567-e89b-12d3-a456-426614174000/vehicle#blue-truck
    • Explanation: This URL initiates an edit action on a vehicle entity with the ID 123e4567-e89b-12d3-a456-426614174000 and a label blue-truck.
  3. Exporting an OS File:
    • Format: #action/entity_id/entity_type
    • Example: #export/98f6bcd4-4dfc-47c3-83b5-b72eac1d459b/os_file
    • Explanation: This URL initiates an export action on an OS file entity with the ID 98f6bcd4-4dfc-47c3-83b5-b72eac1d459b.
  4. Viewing an Entity with Minimal Information:
    • Format: #entity_id
    • Example: #4d8e7c10-f033-11e9-bb60-2a2ae2dbcce4
    • Explanation: This URL points to an entity with the ID 4d8e7c10-f033-11e9-bb60-2a2ae2dbcce4, defaulting to the view action with no specific type or label.
  5. Viewing a Vehicle without a Label:
    • Format: #entity_id/entity_type
    • Example: #5f6b7c8a-d123-45ef-9abc-123d4567e890/vehicle
    • Explanation: This URL points to a vehicle entity with the ID 5f6b7c8a-d123-45ef-9abc-123d4567e890, with no label provided.

Extending the Scheme for Future Actions​

  • Action Prefix: New actions can be added as needed by simply introducing a new prefix before the entity_id. For example, #export/550e8400-e29b-41d4-a716-446655440000/person could be used to export a person entity.
  • Backward Compatibility: URLs without an action prefix or without optional parameters will still function as intended, providing the default view action.

Best Practices​

  • Entity Type: Including the entity_type is recommended whenever possible, as it helps with the clarity and organization of URLs.
  • Entity Label: Use the entity_label to make URLs more user-friendly, especially in cases where the entity ID does not provide enough context on its own.