developmentseed / developmentseed/cng-sandbox
feat: use pystac-client for STAC API interactions
- Dominant language
- TypeScript
- Stars
- 3
- Forks
- 0
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
## Summary
Replace raw `httpx` calls to the STAC API with [pystac-client](https://github.com/stac-utils/pystac-client) — the standard Python client for searching and interacting with STAC APIs.
## Why
- **Type safety**: pystac-client returns `pystac.Item` objects instead of raw dicts, catching schema issues earlier
- **Built-in search**: Filtering by bbox, datetime, and collection is handled by the library instead of manual query string construction
- **Ecosystem alignment**: We already use `pystac` and `rio-stac` for item creation; pystac-client completes the read side
- **Maintainability**: Less hand-rolled HTTP code to maintain; retry logic and pagination handled by the library
## Current usage
The ingestion service talks to the STAC API via `httpx` for:
- Registering new STAC items/collections after conversion
- Checking if items or collections already exist
- Any other STAC API calls in the ingestion pipeline
## Implementation
1. Add `pystac-client` to `pyproject.toml`
2. Create a shared STAC client helper that initializes `pystac_client.Client.open(STAC_API_URL)`
3. Replace `httpx.post` / `httpx.get` calls to the STAC API with pystac-client equivalents:
- Item registration: `client.get_collection().add_item()` or POST via the transactions extension
- Collection creation: use the transactions extension client
- Item/collection lookups: `client.search()` or `client.get_collection()`
4. Keep `httpx` for non-STAC endpoints (health checks, tiler probes, etc.)
5. Update tests
## Notes
- pystac-client supports the [STAC Transactions extension](https://github.com/stac-api-extensions/transaction) which our stac-fastapi instance has enabled (`ENABLE_TRANSACTIONS_EXTENSIONS: "TRUE"`), so write operations should work through the client
- The internal STAC URL (`http://stac-api:8080`) works fine as the client endpoint
## Acceptance criteria
- [ ] All STAC API reads/writes in the ingestion service use pystac-client
- [ ] Raw httpx calls to STAC endpoints are removed
- [ ] Existing ingestion tests pass
- [ ] End-to-end: upload a raster file, verify STAC item is registered and tiles serve
Contributor guide
Research direction
Start by inspecting the ingestion service's existing httpx calls to STAC endpoints and pyproject.toml, then review the current ingestion tests. Trace reads, writes, lookups, and transaction support before choosing the shared client boundary. Done means STAC interactions use pystac-client, non-STAC httpx calls remain, tests pass, and the raster upload end-to-end check verifies item registration and tile serving.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, data
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100