developmentseed / developmentseed/stac-react
Improve `useItem` API to accept collection and item IDs instead of full URL
- Dominant language
- TypeScript
- Stars
- 34
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Description
The current `useItem` hook requires users to pass the full URL of an item, which is redundant and inconsistent with other hooks in the library:
```typescript
// Current API
const { item } = useItem('https://stac-catalog.com/collections/sentinel-2/items/abc123');
```
This design has several issues:
1. **Redundancy**: The `StacApiProvider` already knows the base API URL, yet users must construct the full URL themselves
2. **Error-prone**: Manual URL construction can lead to mistakes (typos, wrong separators, encoding issues)
3. **Not portable**: Hardcoded URLs make switching between environments (dev/staging/prod) difficult
4. **Inconsistent API**: `useCollection` takes just a `collectionId`, but `useItem` requires a full URL
## Proposed Solution
Refactor `useItem` to accept `collectionId` and `itemId` parameters, then construct the URL internally using the `stacApi` from context:
```typescript
// Proposed API
const { item } = useItem('sentinel-2', 'abc123');
// Or with an object for clarity:
const { item } = useItem({ collectionId: 'sentinel-2', itemId: 'abc123' });
```
This follows the STAC API spec pattern: `/collections/{collectionId}/items/{itemId}`
## Benefits
1. **Consistency**: Matches the pattern used by `useCollection`
2. **Simplicity**: No manual URL construction required
3. **Portability**: Environment-agnostic (base URL comes from context)
4. **Type safety**: Parameters are clearly defined
5. **Less error-prone**: Reduces chance of URL construction mistakes
## Implementation Details
The hook would:
1. Accept `collectionId` and `itemId` as parameters
2. Get `stacApi` from `useStacApiContext()`
3. Construct the URL using `stacApi.baseUrl` + `/collections/${collectionId}/items/${itemId}`
4. Use this constructed URL for the query
## Breaking Change
⚠️ This is a **breaking change** that would require a major version bump.
The hook could detect which signature is being used based on the number/type of arguments.
## Related
- Consider whether other hooks might benefit from similar improvements
- Update documentation and examples
- Add migration guide if this is a breaking change
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.