Raise an error on APILayoutStrategy when root_href is non-url

CHANGELOG.md

@@ -17,6 +17,7 @@
 - Update migrate code to handle license changes in STAC spec 1.1.0 ([#1491](https://github.com/stac-utils/pystac/pull/1491))
 - Allow links to have `file://` prefix - but don't write them that way by default ([#1489](https://github.com/stac-utils/pystac/pull/1489))
 - Raise `STACError` with message when a link is expected to resolve to a STAC object but doesn't ([#1500](https://github.com/stac-utils/pystac/pull/1500))
+- Raise an error on APILayoutStrategy when root_href is non-url ([#1498](https://github.com/stac-utils/pystac/pull/1498))
 
 ### Fixed
 

pystac/catalog.py

@@ -14,8 +14,9 @@
 
 import pystac
 from pystac.cache import ResolvedObjectCache
-from pystac.errors import STACTypeError
+from pystac.errors import STACError, STACTypeError
 from pystac.layout import (
+    APILayoutStrategy,
     BestPracticesLayoutStrategy,
     HrefLayoutStrategy,
     LayoutTemplate,
@@ -30,6 +31,7 @@
 from pystac.utils import (
     HREF,
     StringEnum,
+    _is_url,
     is_absolute_href,
     make_absolute_href,
     make_relative_href,
@@ -769,6 +771,9 @@ def normalize_hrefs(
         if not is_absolute_href(root_href):
             root_href = make_absolute_href(root_href, os.getcwd(), start_is_dir=True)
 
+        if isinstance(_strategy, APILayoutStrategy) and not _is_url(root_href):
+            raise STACError("When using APILayoutStrategy the root_href must be a URL")
+
         def process_item(
             item: Item, _root_href: str, is_root: bool, parent: Catalog | None
         ) -> Callable[[], None] | None:

pystac/stac_io.py

@@ -16,7 +16,7 @@
     merge_common_properties,
     migrate_to_latest,
 )
-from pystac.utils import HREF, safe_urlparse
+from pystac.utils import HREF, _is_url, safe_urlparse
 
 # Use orjson if available
 try:
@@ -391,11 +391,6 @@ def _report_duplicate_object_names(
         return result
 
 
-def _is_url(href: str) -> bool:
-    parsed = safe_urlparse(href)
-    return parsed.scheme not in ["", "file"]
-
-
 if HAS_URLLIB3:
     from typing import cast
 

pystac/utils.py

@@ -606,3 +606,9 @@ def is_file_path(href: str) -> bool:
     """
     parsed = urlparse(href)
     return bool(os.path.splitext(parsed.path)[1])
+
+
+def _is_url(href: str) -> bool:
+    """Checks if an HREF is a url rather than a local path"""
+    parsed = safe_urlparse(href)
+    return parsed.scheme not in ["", "file"]

tests/test_catalog.py

@@ -26,6 +26,7 @@
 )
 from pystac.errors import STACError
 from pystac.layout import (
+    APILayoutStrategy,
     BestPracticesLayoutStrategy,
     HrefLayoutStrategy,
     TemplateLayoutStrategy,
@@ -1969,3 +1970,15 @@ def test_add_item_layout_strategy(
     template = template.format(id=item.id).replace("$", "")
 
     assert item.self_href == f"{base_url}/{template}/{item_id}.json"
+
+
+def test_APILayoutStrategy_requires_root_to_be_url(
+    catalog: Catalog, collection: Collection, item: Item
+) -> None:
+    collection.add_item(item)
+    catalog.add_child(collection)
+    with pytest.raises(
+        pystac.errors.STACError,
+        match="When using APILayoutStrategy the root_href must be a URL",
+    ):
+        catalog.normalize_hrefs(root_href="issues-1486", strategy=APILayoutStrategy())