Rest Data Provider

npm i @refinedev/rest

pnpm add @refinedev/rest

yarn add @refinedev/rest

import { createDataProvider } from "@refinedev/rest";

const MyDataProvider = createDataProvider(
  "https://example.com",
  {}, // Create Data Provider Options
  {}, // KY Options
);

export type CreateDataProviderOptions = {
  getList?: {
    /* list records */
  };
  getOne?: {
    /* get record by id */
  };
  getMany?: {
    /* get many by ids */
  };
  create?: {
    /* create record */
  };
  update?: {
    /* update record */
  };
  deleteOne?: {
    /* delete record */
  };
  custom?: {
    /* anything special (search, export, etc.) */
  };
};

export const myDataProvider: CreateDataProviderOptions = {
  getList: {
    // 1. Define the endpoint (optional - defaults to resource name)
    getEndpoint: ({ resource }) => resource, // "posts" → "/posts"

    // 2. Transform Refine's parameters into your API's query format
    buildQueryParams: async ({ pagination, filters, sorters }) => {
      const query: Record<string, any> = {};

      // Handle pagination
      // Refine provides: { current: 1, pageSize: 10 }
      // API expects: ?page=1&size=10
      query.page = pagination?.current ?? 1;
      query.size = pagination?.pageSize ?? 10;

      // Handle sorting
      // Refine provides: [{ field: "createdAt", order: "desc" }]
      // API expects: ?sort[createdAt]=title
      if (sorters?.length) {
        query.sort = sorters.map({ field, order }) => ({ field: order })
      }

      // Handle filters
      // Refine provides: [{ field: "status", operator: "eq", value: "PUBLISHED" }]
      // API expects: ?status=PUBLISHED&title_like=react
      for (const filter of filters ?? []) {
        if (filter.operator === 'eq') {
          query[filter.field] = filter.value;
        }
        if (filter.operator === 'contains') {
          query[`${filter.field}_like`] = filter.value;
        }
        // Add more operators as needed (ne, gt, lt, etc.)
      }

      return query;
    },

    // 3. Extract the data array from API response
    mapResponse: async (response) => {
      const json = await response.json();
      // Your API returns: { data: [...], total: 123 }
      // Refine needs: [...]
      return json.data;
    },

    // 4. Extract the total count for pagination
    getTotalCount: async (response) => {
      const json = await response.json();
      // Your API returns: { data: [...], total: 123 }
      // Refine needs: 123
      return json.total;
    },
  },
};

{ "data": { "id": 123, "title": "My Post", "content": "..." } }

{ "id": 123, "title": "My Post", "content": "..." }

export const myDataProvider: CreateDataProviderOptions = {
  getOne: {
    // Build the endpoint with the ID
    getEndpoint: ({ resource, id }) => `${resource}/${id}`, // "posts/123"

    // Add custom header
    buildHeaders: async ({ resource, id }) => ({
      "Accept-Language": "en-US",
    }),

    // Add query parameters if needed
    buildQueryParams: async ({ resource, id }) => {
      const params: Record<string, any> = {};

      if (resource === "posts") {
        // Load author details with the post
        params.expand = "author";
      }

      return params;
    },

    // Extract the record from API response
    mapResponse: async (response, params) => {
      const json = await response.json();

      // Your API returns different response only for categories.
      if (params.resource === "categories") {
        return json.result;
      }

      // Your API wraps the record in a "data" property
      // API returns: { "data": { "id": 123, "title": "My Post" } }
      // Refine needs: { "id": 123, "title": "My Post" }
      return json.data;
    },
  },
};

{ "data": { "id": 124, "title": "My Post", "content": "Hello world" } }

{ "id": 124, "title": "My Post", "content": "Hello world" }

export const myDataProvider: CreateDataProviderOptions = {
  create: {
    // Build the endpoint for creating records
    getEndpoint: ({ resource }) => resource, // "posts" → "/posts"

    // Add required headers for POST requests
    buildHeaders: async ({ resource, variables }) => ({
      "Accept-Language": "en-US",
    }),

    // Transform form data into API request body
    buildBodyParams: async ({ resource, variables }) => {
      // Refine provides: { title: "My Post", content: "Hello world" }
      // API expects: { dto: { title: "My Post", content: "Hello world", status: "DRAFT" }}
      return {
        dto: {
          ...variables,
          status: "DRAFT", // Add default status
        },
      };
    },

    // Extract the created record from API response
    mapResponse: async (response, params) => {
      const json = await response.json();

      // Your API wraps the created record in a "data" property
      // API returns: { "data": { "id": 124, "title": "My Post" } }
      // Refine needs: { "id": 124, "title": "My Post" }
      return json.data;
    },

    // Handle API errors and convert to form validation errors
    transformError: async (response) => {
      const json = await response.json();

      // API returns validation errors in different formats:
      // {
      //   "error": "Validation failed",
      //   "field_errors": {
      //     "title": ["Title is required"],
      //     "email": ["Invalid format", "Already exists"],
      //   }
      // }
      // Refine expects:
      // {
      //   message: 'Validation failed',
      //   statusCode: 422,
      //   errors: [
      //     { title: ['Title is required'] },
      //     { email: ['InvalidFormat', 'Already exists] }
      //   ]
      // }

      return {
        message: json.error || "Something went wrong",
        statusCode: response.status,
        errors: json.field_errors,
      };
    },
  },
};

update​

The update method handles updating existing records. This powers your edit forms, inline editors, and any component that needs to modify existing data in your API.

Understanding the Data Flow

The data flow for update involves sending modified form data to your API:

Refine Hooks → Your Data Provider → API → Your Data Provider → Refine

Refine provides the record ID and form variables, you build the endpoint and request body, send the data, and return the updated record.

What Refine Provides

Refine calls update with these parameters:

• resource: the collection name (e.g. "posts")
• id: the unique identifier of the record to update
• variables: the form data with changes (e.g. { title: "Updated Title", content: "..." })
• meta: optional metadata for custom behavior

What Your API Expects

Your API likely expects a PUT or PATCH request with the updated data:

{
  "data": { "id": 123, "title": "Updated Title", "content": "Updated content" }
}

{ "id": 123, "title": "Updated Title", "content": "Updated content" }

export const myDataProvider: CreateDataProviderOptions = {
  update: {
    // Build the endpoint with the record ID
    getEndpoint: ({ resource, id }) => `${resource}/${id}`, // "posts/123"

    // Add required headers for put/patch requests
    getRequestMethod: (params: UpdateParams<any>) => 'put'

    buildHeaders: async ({ resource, id, variables }) => ({
      'Accept-Language': 'en-US',
    }),

    // Add query parameters if needed
    buildQueryParams: async ({ resource, id, variables }) => {
      const params: Record<string, any> = {};

      if (resource === 'posts') {
        // Return updated record with author details
        params.expand = 'author';
      }

      return params;
    },

    // Transform form data into API request body
    buildBodyParams: async ({ resource, id, variables }) => {
      // Refine provides: { title: "Updated Title", content: "Updated content" }
      // API expects: { dto: { title: "Updated Title", content: "Updated content", updatedAt: "2025-09-24T..." }}
      return {
        dto: {
          ...variables,
          updatedAt: new Date().toISOString(),
        }
      };
    },

    // Extract the updated record from API response
    mapResponse: async (response, params) => {
      const json = await response.json();

      // Handle different response formats per resource
      if (params.resource === 'categories') {
        return json.result;
      }

      // Your API wraps the updated record in a "data" property
      // API returns: { "data": { "id": 123, "title": "Updated Title" } }
      // Refine needs: { "id": 123, "title": "Updated Title" }
      return json.data;
    },

    // Handle API errors and convert to form validation errors
    transformError: async (response) => {
      const json = await response.json();

      // API returns validation errors:
      // {
      //   "error": "Validation failed",
      //   "field_errors": {
      //     "title": ["Title cannot be empty"],
      //     "email": ["Invalid format"],
      //   }
      // }

      return {
        message: json.error || 'Update failed',
        statusCode: response.status,
        errors: json.field_errors,
      };
    },
  },
};

Example API Format:

• Endpoint: https://example.com/posts/123
• Method: DELETE
• Body: Optional (for soft deletes or additional data)
• Response: { "data": { "id": 123, "title": "Deleted Post" } } or { "success": true } :::

What Refine Expects Back

Refine expects the deleted record object for confirmation and optimistic updates:

API returns:

{ "data": { "id": 123, "title": "Deleted Post" } }

Refine expects:

{ "id": 123, "title": "Deleted Post" }

Available Methods

The deleteOne configuration object provides these methods to transform requests and responses:

• getEndpoint: Builds the API endpoint path with the record ID
• buildHeaders: Adds authentication tokens or custom headers
• buildQueryParams: Adds query parameters to the request
• buildBodyParams: Transforms variables into request body (for soft deletes)
• mapResponse: Extracts the deleted record from your API response
• transformError: Converts API errors into user-friendly error messages

Implementation Example

export const myDataProvider: CreateDataProviderOptions = {
  deleteOne: {
    // Build the endpoint with the record ID
    getEndpoint: ({ resource, id }) => `${resource}/${id}`, // "posts/123"

    // Add required headers for DELETE requests
    buildHeaders: async ({ resource, id, variables }) => ({
      "Accept-Language": "en-US",
    }),

    // Add query parameters if needed
    buildQueryParams: async ({ resource, id, variables }) => {
      const params: Record<string, any> = {};

      if (resource === "posts") {
        // Force hard delete instead of soft delete
        params.force = true;
      }

      return params;
    },

    // Transform variables into request body (for soft deletes)
    buildBodyParams: async ({ resource, id, variables }) => {
      // For soft deletes, send deletion reason or metadata
      if (variables?.softDelete) {
        return {
          deletedAt: new Date().toISOString(),
          deletionReason: variables.reason || "User deleted",
          softDelete: true,
        };
      }

      // Hard delete - no body needed
      return undefined;
    },

    // Extract the deleted record from API response
    mapResponse: async (response, params) => {
      const json = await response.json();

      // Handle different response formats
      if (params.resource === "categories") {
        return json.result;
      }

      // Some APIs return just success confirmation
      if (json.success && !json.data) {
        // Return minimal record with just the ID for confirmation
        return { id: params.id };
      }

      // Your API wraps the deleted record in a "data" property
      // API returns: { "data": { "id": 123, "title": "Deleted Post" } }
      // Refine needs: { "id": 123, "title": "Deleted Post" }
      return json.data;
    },

    // Handle API errors and convert to user-friendly errors
    transformError: async (response) => {
      const json = await response.json();

      // Handle specific delete errors
      if (response.status === 409) {
        return {
          message: "Cannot delete: Record has dependencies",
          statusCode: 409,
        };
      }

      if (response.status === 403) {
        return {
          message: "Not authorized to delete this record",
          statusCode: 403,
        };
      }

      return {
        message: json.error || "Delete failed",
        statusCode: response.status,
      };
    },
  },
};

With this deleteOne implementation, here's what happens when a user deletes a record:

Success scenario:

1. User action: User clicks delete button or confirms deletion in a modal
2. Refine processes: Refine calls deleteOne with the record ID (id: 123, optionally variables: { softDelete: true, reason: "Outdated content" })
3. Your transformation: buildBodyParams formats the request body for soft delete, buildQueryParams adds force parameter if needed
4. API call: DELETE request goes to https://example.com/posts/123?force=true with deletion metadata
5. Response processing: mapResponse extracts the deleted record for confirmation
6. UI update: Refine removes the record from lists and shows success confirmation

Error scenario:

1. API returns error: Server responds with 409 (conflict) or 403 (forbidden) status
2. Error transformation: transformError converts specific HTTP codes into user-friendly messages
3. User feedback: Refine displays contextual error messages like "Cannot delete: Record has dependencies"
4. UI state: Record remains in the list, delete operation is cancelled

Soft delete scenario:

1. User triggers soft delete: Form includes deletion reason and soft delete flag
2. Request body: Contains deletedAt timestamp, reason, and soft delete flag
3. API processing: Server marks record as deleted without removing from database
4. Response: API returns the soft-deleted record with updated status
5. UI update: Record is filtered out of active lists but may appear in "deleted items" view

This pattern ensures reliable record deletion with proper error handling and support for both hard and soft deletion strategies.

The getMany method handles fetching multiple records by their IDs. This powers relationship fields, reference selectors, and any component that needs to load specific records by their identifiers.

Understanding the Data Flow

The data flow for getMany involves sending a request with multiple IDs to your API:

Refine Hooks → Your Data Provider → API → Your Data Provider → Refine

Refine provides an array of IDs, you build the endpoint and query parameters, make the request, and return the matching records.

What Refine Provides

Refine calls getMany with these parameters:

• resource: the collection name (e.g. "posts")
• ids: array of unique identifiers to fetch (e.g. [123, 456, 789])
• meta: optional metadata for custom behavior

What Your API Expects

Your API might handle multiple IDs in different ways:

What Refine Expects Back

Refine expects an array of record objects matching the requested IDs:

API returns:

{
  "data": [
    { "id": 123, "title": "Post 1" },
    { "id": 456, "title": "Post 2" },
    { "id": 789, "title": "Post 3" }
  ]
}

Refine expects:

[
  { "id": 123, "title": "Post 1" },
  { "id": 456, "title": "Post 2" },
  { "id": 789, "title": "Post 3" }
]

Available Methods

The getMany configuration object provides these methods to transform requests and responses:

• getEndpoint: Builds the API endpoint path (defaults to resource name)
• buildHeaders: Adds authentication tokens or custom headers
• buildQueryParams: Transforms ID array into your API's query format
• mapResponse: Extracts the record array from your API response

Implementation Example

export const myDataProvider: CreateDataProviderOptions = {
  getMany: {
    // Build the endpoint for batch requests
    getEndpoint: ({ resource, ids }) => {
      // Use different endpoints based on resource type
      if (resource === "users") {
        return `${resource}/batch`;
      }
      return resource; // "posts"
    },

    // Add required headers
    buildHeaders: async ({ resource, ids }) => ({
      "Accept-Language": "en-US",
    }),

    // Transform ID array into query parameters
    buildQueryParams: async ({ resource, ids }) => {
      const params: Record<string, any> = {};

      // Different query formats based on resource
      if (resource === "posts") {
        // Format: ?ids=123,456,789
        params.ids = ids.join(",");
      } else if (resource === "categories") {
        // Format: ?id[]=123&id[]=456&id[]=789
        params.id = ids;
      }

      // Add expansion for related data
      if (resource === "posts") {
        params.expand = "author,category";
      }

      return params;
    },

    // Extract the record array from API response
    mapResponse: async (response, params) => {
      const json = await response.json();

      // Handle different response formats per resource
      if (params.resource === "categories") {
        return json.results;
      }

      // Your API wraps records in a "data" property
      // API returns: { "data": [{ "id": 123 }, { "id": 456 }] }
      // Refine needs: [{ "id": 123 }, { "id": 456 }]
      return json.data;
    },
  },
};

With this getMany implementation, here's what happens when Refine needs multiple records:

Success scenario:

1. Refine needs records: Reference field or relationship component requests multiple records (ids: [123, 456, 789])
2. Your transformation: buildQueryParams formats IDs as comma-separated string (?ids=123,456,789&expand=author,category)
3. API call: GET request goes to https://example.com/posts?ids=123,456,789&expand=author,category
4. Response processing: mapResponse extracts the record array from wrapped response
5. UI update: Refine displays the records in select options, relationship fields, or reference components

Fallback behavior scenario:

1. No getMany implemented: You only implement getOne in your data provider
2. Refine needs multiple records: Component requests records with ids: [123, 456, 789]
3. Automatic fallback: Refine makes three separate getOne calls: getOne({ resource: "posts", id: 123 }), getOne({ resource: "posts", id: 456 }), getOne({ resource: "posts", id: 789 })
4. Performance impact: Three HTTP requests instead of one batch request
5. UI behavior: Same end result, but slower loading times

Large ID array scenario:

1. Many IDs requested: Component requests 100+ records at once
2. Query parameter handling: Your API must handle long query strings with many IDs
3. API call: GET request with all IDs in query parameters (URL length limits may apply)
4. Response processing: Same mapResponse logic handles the response
5. Consideration: If URL length becomes an issue, consider implementing a custom method using the custom data provider method with POST requests

Partial results scenario:

1. Some IDs missing: API returns records for IDs 123 and 456 but not 789
2. Response processing: mapResponse returns available records [{ id: 123 }, { id: 456 }]
3. UI handling: Refine components gracefully handle missing records (show placeholder or skip)
4. No error thrown: Missing records are handled as normal behavior, not errors

This pattern ensures reliable batch record fetching with support for different API designs, large datasets, and graceful error handling.