developmentseed / developmentseed/cng-sandbox

feat: use pystac-client for STAC API interactions

Open
#64 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.