Update readme

Author: jonhealy1

README.md

@@ -92,6 +92,7 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
   - [Technologies](#technologies)
   - [Table of Contents](#table-of-contents)
   - [Collection Search Extensions](#collection-search-extensions)
+  - [Catalogs Route](#catalogs-route)
   - [Documentation & Resources](#documentation--resources)
   - [SFEOS STAC Viewer](#sfeos-stac-viewer)
   - [Package Structure](#package-structure)
@@ -168,6 +169,8 @@ SFEOS provides enhanced collection search capabilities through two primary route
 - **GET/POST `/collections`**: The standard STAC endpoint with extended query parameters
 - **GET/POST `/collections-search`**: A custom endpoint that supports the same parameters, created to avoid conflicts with the STAC Transactions extension if enabled (which uses POST `/collections` for collection creation)
 
+The `/collections-search` endpoint follows the [STAC API Collection Search Endpoint](https://github.com/Healy-Hyperspatial/stac-api-extensions-collection-search-endpoint) specification, which provides a dedicated, conflict-free mechanism for advanced collection searching.
+
 These endpoints support advanced collection discovery features including:
 
 - **Sorting**: Sort collections by sortable fields using the `sortby` parameter
@@ -227,6 +230,64 @@ These extensions make it easier to build user interfaces that display and naviga
 > **Important**: Adding keyword fields to make text fields sortable can significantly increase the index size, especially for large text fields. Consider the storage implications when deciding which fields to make sortable.
 
 
+## Catalogs Route
+
+SFEOS supports hierarchical catalog browsing through the `/catalogs` endpoint, enabling users to navigate through STAC catalog structures in a tree-like fashion. This extension allows for organized discovery and browsing of collections and sub-catalogs.
+
+This implementation follows the [STAC API Catalogs Extension](https://github.com/Healy-Hyperspatial/stac-api-extensions-catalogs) specification, which enables a Federated STAC API architecture with a "Hub and Spoke" structure.
+
+### Features
+
+- **Hierarchical Navigation**: Browse catalogs and sub-catalogs in a parent-child relationship structure
+- **Collection Discovery**: Access collections within specific catalog contexts
+- **STAC API Compliance**: Follows STAC specification for catalog objects and linking
+- **Flexible Querying**: Support for standard STAC API query parameters when browsing collections within catalogs
+
+### Endpoints
+
+- **GET `/catalogs`**: Retrieve the root catalog and its child catalogs
+- **POST `/catalogs`**: Create a new catalog (requires appropriate permissions)
+- **GET `/catalogs/{catalog_id}`**: Retrieve a specific catalog and its children
+- **GET `/catalogs/{catalog_id}/collections`**: Retrieve collections within a specific catalog
+- **GET `/catalogs/{catalog_id}/collections/{collection_id}`**: Retrieve a specific collection within a catalog
+- **GET `/catalogs/{catalog_id}/collections/{collection_id}/items`**: Retrieve items within a collection in a catalog context
+- **GET `/catalogs/{catalog_id}/collections/{collection_id}/items/{item_id}`**: Retrieve a specific item within a catalog context
+
+### Usage Examples
+
+```bash
+# Get root catalog
+curl "http://localhost:8081/catalogs"
+
+# Get specific catalog
+curl "http://localhost:8081/catalogs/earth-observation"
+
+# Get collections in a catalog
+curl "http://localhost:8081/catalogs/earth-observation/collections"
+
+# Get specific collection within a catalog
+curl "http://localhost:8081/catalogs/earth-observation/collections/sentinel-2"
+
+# Get items in a collection within a catalog
+curl "http://localhost:8081/catalogs/earth-observation/collections/sentinel-2/items"
+
+# Get specific item within a catalog
+curl "http://localhost:8081/catalogs/earth-observation/collections/sentinel-2/items/S2A_20231015_123456"
+```
+
+### Response Structure
+
+Catalog responses include:
+- **Catalog metadata**: ID, title, description, and other catalog properties
+- **Child catalogs**: Links to sub-catalogs for hierarchical navigation
+- **Collections**: Links to collections contained within the catalog
+- **STAC links**: Properly formatted STAC API links for navigation
+
+This feature enables building user interfaces that provide organized, hierarchical browsing of STAC collections, making it easier for users to discover and navigate through large collections organized by theme, provider, or any other categorization scheme.
+
+> **Configuration**: The catalogs route can be enabled or disabled by setting the `ENABLE_CATALOGS_ROUTE` environment variable to `true` or `false`. By default, this endpoint is **disabled**.
+
+
 ## Package Structure
 
 This project is organized into several packages, each with a specific purpose:
@@ -360,6 +421,7 @@ You can customize additional settings in your `.env` file:
 | `ENABLE_COLLECTIONS_SEARCH`  | Enable collection search extensions (sort, fields, free text search, structured filtering, and datetime filtering) on the core `/collections` endpoint. | `true`                   | Optional                                                                                    |
 | `ENABLE_COLLECTIONS_SEARCH_ROUTE` | Enable the custom `/collections-search` endpoint (both GET and POST methods). When disabled, the custom endpoint will not be available, but collection search extensions will still be available on the core `/collections` endpoint if `ENABLE_COLLECTIONS_SEARCH` is true. | `false` | Optional |
 | `ENABLE_TRANSACTIONS_EXTENSIONS` | Enables or disables the Transactions and Bulk Transactions API extensions. This is useful for deployments where mutating the catalog via the API should be prevented. If set to `true`, the POST `/collections` route for search will be unavailable in the API. | `true` | Optional |
+| `ENABLE_CATALOGS_ROUTE` | Enable the `/catalogs` endpoint for hierarchical catalog browsing and navigation. When enabled, provides access to federated STAC API architecture with hub-and-spoke pattern. | `false` | Optional |
 | `STAC_GLOBAL_COLLECTION_MAX_LIMIT` | Configures the maximum number of STAC collections that can be returned in a single search request. | N/A | Optional |
 | `STAC_DEFAULT_COLLECTION_LIMIT` | Configures the default number of STAC collections returned when no limit parameter is specified in the request. | `300` | Optional |
 | `STAC_GLOBAL_ITEM_MAX_LIMIT` | Configures the maximum number of STAC items that can be returned in a single search request. | N/A | Optional |