URL Management

URL mapping query and dynamic resolution

Query URL mappings with dynamic resolution

get

Returns stored URL mappings matching the query criteria. When no stored mapping exists, automatically performs dynamic resolution by analyzing the application's routing configuration.

Query Strategies:

1. Path-Based Query (new_path or old_path parameter)

• Searches stored mappings first

• If not found, activates dynamic resolution

• Returns view metadata, route parameters, and query strings

• Suitable for navigation and redirection logic

2. Unified Path Query (path parameter)

• Searches new_path field first, then falls back to old_path

• Automatically tries both path formats in sequence

3. Product-Specific Redirection (path parameter with product ID format)

• Detects product ID patterns (e.g., /product/123/)

• Automatically resolves to sibling product URL when original is unavailable

• Returns HTTP redirect response instead of JSON

• Used for maintaining product navigation when items are delisted

4. Advanced Filtering (multiple filter parameters)

• Combine language, parent, and date range filters

• Returns paginated list of stored mappings only

Dynamic Resolution Details:

When a path query returns zero stored results, the system:

1. Parses the URL to separate path and query components

2. Resolves the path through the application routing engine

3. Extracts view module, function name, and initialization parameters

4. Captures route arguments, keyword arguments, and query parameters

5. Returns a synthesized response with all routing metadata

This ensures navigation never fails for valid application URLs, even if they haven't been explicitly stored in the URL registry.

Query parameters

new_pathstring · uri-referenceOptional

Filter by the display URL path (human-readable, SEO-friendly format).

Query Behavior:

• Searches the new_path field for exact matches
• If no stored mapping found, triggers dynamic resolution
• Path is automatically normalized (leading/trailing slashes added based on configuration)

Example Values:

• /products/shoes/running-shoes/
• /categories/electronics/
• /special-offers/

Dynamic Resolution Example: If you query /products/new-arrival/ and no stored mapping exists, the system will resolve it through the routing engine and return view metadata for that path.

Example: /products/shoes/

old_pathstring · uri-referenceOptional

Filter by the canonical URL path (original application route).

Query Behavior:

• Searches the old_path field for exact matches
• If no stored mapping found, triggers dynamic resolution
• Typically represents the internal application route before prettification

Example Values:

• /product-detail/123/
• /category/45/
• /cms/page/about-us/

Use Case: Query old paths when you need to find what pretty URL maps to a specific internal route, or when resolving legacy URLs after a site migration.

Example: /product-detail/123/

pathstring · uri-referenceOptional

Unified path search that checks both display and canonical paths.

Search Order:

1. First searches new_path field
2. If no match, searches old_path field
3. If still no match, triggers dynamic resolution

Special Behavior - Product Redirection: When the path matches a product URL pattern (contains "product" keyword and numeric ID), the system attempts to redirect to a sibling product if the original is unavailable. This returns an HTTP 302 redirect response instead of JSON.

Example Values:

• /products/shoes/ (standard path)
• /product/456/ (triggers product redirection logic)
• /category/electronics/ (standard path)

Convenience Use Case: Use this parameter when you don't know whether the path is stored as a pretty URL or canonical URL. The system will automatically try both.

Example: /products/shoes/

new_path__exactstring · uri-referenceOptional

Performs an exact match search on the display URL path.

Difference from new_path:

• Does NOT trigger dynamic resolution if no match found
• Returns empty results when no stored mapping exists
• Useful for checking if a specific pretty URL is already registered

Use Case: Use this when you want to verify the existence of a stored mapping without triggering fallback resolution, such as during URL uniqueness validation or administrative checks.

Example: /products/shoes/

languagestring · min: 2 · max: 10Optional

Filter by language code for multi-language URL mappings.

Behavior:

• Returns only URLs assigned to the specified language
• Supports standard language codes (e.g., en, tr, ar, de)
• Null language values represent language-neutral URLs

Multi-Language Configuration: When multi-language mode is enabled (Source: Static System Configuration), each URL can have language-specific variants stored as child mappings. Parent URLs typically have a default or null language value.

Example Values:

• en - English
• tr - Turkish
• ar - Arabic
• de - German

Use Case: Essential for international storefronts where the same logical page has different URL paths per language for SEO optimization.

Example: en

parentintegerOptional

Filter by parent URL identifier for hierarchical URL structures.

Hierarchy Model:

• Parent URLs represent the primary, language-neutral mapping
• Child URLs (via prettyurl_set) represent language-specific variants
• Top-level URLs have parent=null

Query Options:

• Provide a parent ID to find all child language variants
• Omit to include all URL levels in results
• Combine with language filter to find specific language variants of a parent

Example: If parent URL /products/shoes/ has ID 42, querying parent=42 returns all language-specific child URLs like /tr/urunler/ayakkabi/, /ar/منتجات/أحذية/, etc.

Use Case: Navigate URL hierarchies when managing multi-language content or discovering all language variants of a specific page.

Example: 1

created_date__gtstring · date-timeOptional

Filter URLs created after the specified datetime (exclusive).

Format: ISO 8601 datetime with timezone Example: 2024-01-01T00:00:00Z

Returns only stored mappings created after this timestamp. Useful for tracking recently added URLs or monitoring URL generation activities.

Example: 2024-01-01T00:00:00Z

created_date__gtestring · date-timeOptional

Filter URLs created on or after the specified datetime (inclusive).

Format: ISO 8601 datetime with timezone Example: 2024-01-01T00:00:00Z

Returns stored mappings created at or after this timestamp. Useful for date-range queries and reporting.

Example: 2024-01-01T00:00:00Z

created_date__ltstring · date-timeOptional

Filter URLs created before the specified datetime (exclusive).

Format: ISO 8601 datetime with timezone Example: 2024-12-31T23:59:59Z

Returns only stored mappings created before this timestamp. Useful for historical analysis or finding legacy URLs.

Example: 2024-12-31T23:59:59Z

created_date__ltestring · date-timeOptional

Filter URLs created on or before the specified datetime (inclusive).

Format: ISO 8601 datetime with timezone Example: 2024-12-31T23:59:59Z

Returns stored mappings created at or before this timestamp. Completes date-range query capabilities.

Example: 2024-12-31T23:59:59Z

modified_date__gtstring · date-timeOptional

Filter URLs modified after the specified datetime (exclusive).

Format: ISO 8601 datetime with timezone

Returns only stored mappings updated after this timestamp. Essential for tracking URL changes and synchronization activities.

Example: 2024-01-01T00:00:00Z

modified_date__gtestring · date-timeOptional

Filter URLs modified on or after the specified datetime (inclusive).

Format: ISO 8601 datetime with timezone

Returns stored mappings updated at or after this timestamp.

Example: 2024-01-01T00:00:00Z

modified_date__ltstring · date-timeOptional

Filter URLs modified before the specified datetime (exclusive).

Format: ISO 8601 datetime with timezone

Returns only stored mappings updated before this timestamp.

Example: 2024-12-31T23:59:59Z

modified_date__ltestring · date-timeOptional

Filter URLs modified on or before the specified datetime (inclusive).

Format: ISO 8601 datetime with timezone

Returns stored mappings updated at or before this timestamp.

Example: 2024-12-31T23:59:59Z

pageinteger · min: 1Optional

Page number for paginated results.

Default: 1 (first page) Behavior: Returns the specified page of results based on the configured page size

Pagination applies only to stored mappings. Dynamic resolution always returns a single result (count=1).

Default: 1Example: 1

page_sizeinteger · min: 1Optional

Number of items per page.

Limits: Subject to system-configured maximum page size Default: Determined by pagination configuration (typically 10)

Allows clients to control result density. Larger page sizes reduce request count but increase response size.

Example: 20

Responses

200

Successfully retrieved URL mappings or performed dynamic resolution.

Response Types:

1. Stored Mappings Found (count > 0)

• Contains database records with all metadata
• Includes timestamps (created_date, modified_date)
• May include hierarchical relationships (parent and child URLs)
• Paginated when multiple results exist

2. Dynamic Resolution Performed (count = 1, timestamps null)

• Contains synthesized routing information
• created_date and modified_date are null
• pk is absent (no database identifier)
• Single result with resolved view metadata

3. No Results (count = 0)

• Occurs when using advanced filters without path parameters
• Indicates no stored mappings match the criteria
• Empty results array

Pagination Notes:

• next: URL to retrieve the next page (null if on last page)
• previous: URL to retrieve the previous page (null if on first page)
• count: Total number of matching URLs across all pages

application/json

302

Redirect to sibling product URL.

Trigger Condition: When querying with the path parameter containing a product ID format (e.g., /product/123/) and the system determines the original product is unavailable.

Redirection Logic:

1. Extracts product ID from the path
2. Loads the product record
3. Checks product type and availability status
4. Selects an appropriate sibling or parent product
5. Returns HTTP 302 redirect to the new product's URL

Product Type Handling:

• Simple Products: Redirects to parent product if available
• Parent Products: Redirects to first listable variant
• Falls back to 404 if no suitable sibling exists

Configuration: This behavior can be enabled or disabled at runtime (Source: Dynamic/Real-time Configuration) to control whether unavailable products redirect to alternatives or return errors.

404

URL path could not be resolved.

Occurrence Scenarios:

1. Invalid Application Route: The provided path does not match any configured application route and cannot be resolved dynamically. This indicates the path is not a valid application URL.

2. Product Redirection Failed: When using the path parameter with product ID format, the product was not found or has no available siblings to redirect to.

Distinction from 200 with count=0:

• 404: The path itself is invalid or unresolvable
• 200 with count=0: The path is valid but no stored mapping exists, or filters excluded all results

application/json

get

/pretty_urls/

HTTPcURLJavaScriptPython

GET /pretty_urls/ HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "pk": 1523,
      "new_path": "/products/running-shoes/",
      "old_path": "/product-detail/456/",
      "parent": null,
      "language": "en",
      "func_module": "omnishop.products.views",
      "func_name": "ProductDetailView",
      "func_initkwargs": {
        "model": "Product"
      },
      "args": [],
      "kwargs": {
        "pk": "456"
      },
      "query_params": {},
      "viewname": "product-detail",
      "created_date": "2024-11-15T10:30:00Z",
      "modified_date": "2024-11-20T14:22:00Z",
      "prettyurl_set": [
        {
          "pk": 1524,
          "new_path": "/tr/urunler/kosu-ayakkabilari/",
          "language": "tr"
        },
        {
          "pk": 1525,
          "new_path": "/ar/منتجات/أحذية-الجري/",
          "language": "ar"
        }
      ]
    }
  ]
}