Merge pull request #1217 from radiantearth/resolve-links

Fine-tune best practice for URLs

best-practices.md

@@ -152,12 +152,21 @@ For data providers using STAC with requester pays buckets, there are two main re
 Links in STAC can be [absolute or relative](#use-of-links).
 Relative links must be resolved against the absolute URI given in the link with the relation type `self` (or in some cases `root`).
 To resolve relative URIs the base URIs must be precise and consistent: Having or not having a trailing slash is significant.
-Without it, the last path component is considered to be a "file" name to be removed to get at the "directory" that is used as the base.
+Without it, the last path component is identified as a "file" name which will be removed to get to the "directory" that is used as the base.
 API endpoints usually behave like directories.
+This means that if the trailing slash is missing for a folder,
+a relative link would need to include the last path component again to resolve correctly.
 
 **Examples:**
-- <https://example.com/folder/catalog.json> is good and <https://example.com/folder/catalog.json/> is problematic as catalog.json is a specific file
-- <https://example.com/api/> is good and <https://example.com/api> is problematic as `api` should not be removed when resolving URIs.
+- We have a `self` link `https://example.com/folder/catalog.json` and a relative link `./item.json`.
+  This resolves to `https://example.com/folder/item.json` as expected as the last path component is actually a file.
+- We have a `self` link `https://example.com/collections/S2/items/123` and a relative link `./band1.tif`.
+  This resolves to `https://example.com/collections/S2/items/band1.tif`, which is likely unexpected and unintended.
+  There are two ways to solve this issue so that the URLs resolve correctly to `https://example.com/collections/S2/items/123/band1.tif`:
+  1. Add a slash at the end of the `self` link: `https://example.com/collections/S2/items/123/`, *OR*
+  2. Add the last path element to the relative link: `./123/band1.tif`
+
+To avoid these issues it is recommended to consistently add a slash at the end of the URL if it doesn't point to a file.
 
 ## Item Practices