developmentseed / developmentseed/stac-react

Improve `useItem` API to accept collection and item IDs instead of full URL

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.