npm package: @p4it-kft/ra-data-hydra
Description: React-admin data provider for Hydra-enabled APIs with Mercure real-time support.
Author: P4IT Kft.
Latest version: 1.1.0

# @p4it-kft/ra-data-hydra

A [react-admin](https://marmelab.com/react-admin/) data provider for APIs supporting [the Hydra Core Vocabulary](http://www.hydra-cg.com/), including APIs created using [the API Platform framework](https://api-platform.com).

Based on the data provider from [@api-platform/admin](https://github.com/api-platform/admin), extracted as a standalone lightweight package that depends on `ra-core` instead of the full `react-admin` UI bundle.

## Installation

```bash
yarn add @p4it-kft/ra-data-hydra
```

**Note:** This package provides only the data provider. You need `react-admin` (or at minimum `ra-core`) installed in your application.

## Usage

```javascript
import { Admin, Resource, ListGuesser, EditGuesser } from 'react-admin';
import { dataProvider } from '@p4it-kft/ra-data-hydra';

const hydraDataProvider = dataProvider({
  entrypoint: 'https://demo.api-platform.com',
});

const App = () => (
  <Admin dataProvider={hydraDataProvider}>
    <Resource name="books" list={ListGuesser} edit={EditGuesser} />
    <Resource name="reviews" list={ListGuesser} edit={EditGuesser} />
  </Admin>
);

export default App;
```

### With Authentication

```javascript
import { dataProvider, fetchHydra } from '@p4it-kft/ra-data-hydra';

const httpClient = (url, options = {}) => {
  const token = localStorage.getItem('token');
  return fetchHydra(url, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: token ? `Bearer ${token}` : undefined,
    },
  });
};

const hydraDataProvider = dataProvider({
  entrypoint: 'https://demo.api-platform.com',
  httpClient,
});
```

### With Custom API Documentation Parser

```javascript
import { dataProvider } from '@p4it-kft/ra-data-hydra';
import { parseHydraDocumentation } from '@api-platform/api-doc-parser';

const hydraDataProvider = dataProvider({
  entrypoint: 'https://demo.api-platform.com',
  apiDocumentationParser: parseHydraDocumentation,
});
```

## Features

- Parses Hydra API documentation to discover resources and fields
- Implements all react-admin data provider methods (getList, getOne, create, update, delete, etc.)
- Supports pagination, filtering, and sorting
- Handles JSON-LD format and Hydra collections
- Supports file uploads via multipart/form-data
- Supports embedded resources
- TypeScript support with full type definitions

## API

### `dataProvider(options)`

Creates a react-admin data provider for Hydra APIs.

**Options:**
- `entrypoint` (string, required): The API entrypoint URL
- `httpClient` (function): Custom HTTP client (defaults to `fetchHydra`)
- `apiDocumentationParser` (function): Custom API documentation parser
- `mercure` (object|boolean): Mercure real-time updates configuration
- `useEmbedded` (boolean): Enable embedded resource support (default: `true`)
- `disableCache` (boolean): Disable the local embedded documents cache (default: `false`)
- `keyPrefix` (string): The prefix used for Hydra JSON-LD keys in API responses (default: `'hydra:'`). Set to `''` if your API returns unprefixed keys (e.g. `member` instead of `hydra:member`).

### `fetchHydra(url, options)`

HTTP client for Hydra APIs that handles JSON-LD content negotiation.

### `schemaAnalyzer()`

Creates a schema analyzer for extracting field metadata from Hydra documentation.

## Exports

```javascript
// Data provider factory
export { dataProvider } from '@p4it-kft/ra-data-hydra';

// HTTP client
export { fetchHydra } from '@p4it-kft/ra-data-hydra';

// Schema analyzer
export { schemaAnalyzer } from '@p4it-kft/ra-data-hydra';

// Utility
export { transformJsonLdDocumentToReactAdminDocument } from '@p4it-kft/ra-data-hydra';

// Types
export type {
  ApiPlatformAdminRecord,
  ApiPlatformAdminDataProvider,
  HydraDataProviderFactoryParams,
  HydraCollection,
  HydraHttpClientResponse,
  HttpClientOptions,
  MercureOptions,
  SchemaAnalyzer,
  FilterParameter,
  IntrospectPayload,
} from '@p4it-kft/ra-data-hydra';
```

## Documentation

- [react-admin documentation](https://marmelab.com/react-admin/Tutorial.html)
- [Hydra Core Vocabulary](http://www.hydra-cg.com/)
- [API Platform documentation](https://api-platform.com/docs/)

## Credits

Based on the Hydra data provider from [@api-platform/admin](https://github.com/api-platform/admin), originally created by [Kévin Dunglas](https://dunglas.fr).

## License

MIT