Data Fetching & Data Providers

In a shadmin app, you don’t write API calls using fetch or axios. Instead, you communicate with your API through an object called the dataProvider.

This documentation will explain the following concepts:

The dataProvider

Shadmin streamlines data fetching for administrative interfaces through its Data Provider object, which unifies interactions across diverse APIs such as REST and GraphQL. This abstraction allows developers to focus on UI development rather than intricate API calls. It employs specialized hooks, like useGetList and useGetOne, and integrates TanStack Query to manage data efficiently, offering features such as caching and optimistic updates.

The framework also simplifies working with relational APIs and incorporates real-time capabilities for collaborative applications. Authentication is handled by an authProvider, which manages user logins and tokens, subsequently utilized by the dataProvider for secure API requests.

To learn more about the Data Provider, refer to the Data Fetching documentation.

Setup

The first step to using a Data Provider is to pass it to the <Admin> component via the dataProvider prop.

For example, let’s use the Simple REST data provider. This provider is suitable for REST APIs using simple GET parameters for filters and sorting.

First, install the ra-data-simple-rest package:

npm install ra-data-simple-rest

Then, initialize the provider with the REST backend URL, and pass it as the <Admin dataProvider>:

// in src/App.js
import { Admin } from "@/components/admin";
import { Resource } from "ra-core";
import simpleRestProvider from "ra-data-simple-rest";
 
import { PostList } from "./posts";
 
const dataProvider = simpleRestProvider("http://path.to.my.api/");
 
const App = () => (
  <Admin dataProvider={dataProvider}>
    <Resource name="posts" list={PostList} />
  </Admin>
);
 
export default App;

That’s all it takes to make all shadmin components work with your API. They will call the data provider methods, which will in turn call the API. Here’s how the Simple REST data provider maps shadmin calls to API calls:

Method nameAPI call
getListGET http://my.api.url/posts?sort=["title","ASC"]&range=[0, 24]&filter={"title":"bar"}
getOneGET http://my.api.url/posts/123
getManyGET http://my.api.url/posts?filter={"ids":[123,456,789]}
getManyReferenceGET http://my.api.url/posts?filter={"author_id":345}
createPOST http://my.api.url/posts
updatePUT http://my.api.url/posts/123
updateManyMultiple calls to PUT http://my.api.url/posts/123
deleteDELETE http://my.api.url/posts/123
deleteManyMultiple calls to DELETE http://my.api.url/posts/123

For your own API, look for a compatible data provider in the list of supported API backends or write your own.

For more details about the data provider setup, refer to the Data Provider Setup documentation.

Supported Data Provider Backends

Thanks to the Data Provider architecture, shadmin supports a lot of API backends. Check the list below for open-source packages developed and maintained by the core team and developers from the community.

If you can't find a Data Provider for your backend below, no worries! Writing a Data Provider takes a couple of hours, and won't prevent you from using shadmin.

That's a long list!

If you don't know where to start, use any of the following:

Tip: Since dataProviders all present the same interface, you can use one dataProvider during early prototyping / development phases, then switch to the dataProvider that fits your production infrastructure.

If you've written a Data Provider for another backend, and open-sourced it, please help complete this list with your package.

Writing a Data Provider

APIs are so diverse that quite often, none of the available Data Providers suit you API. In such cases, you’ll have to write your own Data Provider. Don’t worry, it usually takes only a couple of hours.

A data provider must implement the following methods:

const dataProvider = {
  // get a list of records based on sort, filter, and pagination
  getList: (resource, params) => Promise,
  // get a single record by id
  getOne: (resource, params) => Promise,
  // get a list of records based on an array of ids
  getMany: (resource, params) => Promise,
  // get the records referenced to another record, e.g. comments for a post
  getManyReference: (resource, params) => Promise,
  // create a record
  create: (resource, params) => Promise,
  // update a record based on a patch
  update: (resource, params) => Promise,
  // update a list of records based on an array of ids and a common patch
  updateMany: (resource, params) => Promise,
  // delete a record by id
  delete: (resource, params) => Promise,
  // delete a list of records based on an array of ids
  deleteMany: (resource, params) => Promise,
};

To call the data provider, shadmin combines a method (e.g. getOne), a resource (e.g. ‘posts’) and a set of parameters.

Tip: In comparison, HTTP requests require a verb (e.g. ‘GET’), an url (e.g. http://myapi.com/posts), a list of headers (like Content-Type) and a body.

To learn more about writing a Data Provider, refer to the Data Provider Writing documentation.

Querying The API

Shadmin provides special hooks to emit read and write queries to the dataProvider, which in turn sends requests to your API. Under the hood, it uses React Query to call the dataProvider and cache the results.

Shadmin provides one query hook for each of the Data Provider read methods. They are useful shortcuts that make your code more readable and more robust. The query hooks execute on mount. They return an object with the following properties: { data, isPending, error }. Query hooks are:

  • useGetList calls dataProvider.getList()
  • useGetOne calls dataProvider.getOne()
  • useGetMany calls dataProvider.getMany()
  • useGetManyReference calls dataProvider.getManyReference()

Their input signature is the same as the related dataProvider method, i.e. they expect the resource name and the query parameters:

const { isPending, error, data } = useGetOne(resource, { id });
// calls dataProvider.getOne(resource, { id })

For instance, here is how to fetch one User record on mount using the useGetOne hook:

import { useGetOne } from "ra-core";
import { Loading, Error } from "./MyComponents";
 
const UserProfile = ({ userId }) => {
  const { isPending, error, data: user } = useGetOne("users", { id: userId });
 
  if (isPending) return <Loading />;
  if (error) return <Error />;
  if (!user) return null;
 
  return (
    <ul>
      <li>Name: {user.name}</li>
      <li>Email: {user.email}</li>
    </ul>
  );
};

Shadmin also provides one mutation hook for each of the Data Provider write methods. These hooks execute the query when you call a callback. They return an array with the following items: [mutate, { data, isPending, error }]. mutate is a callback that you can call to execute the mutation.

Mutation hooks are:

  • useCreate calls dataProvider.create()
  • useUpdate calls dataProvider.update()
  • useUpdateMany calls dataProvider.updateMany()
  • useDelete calls dataProvider.delete()
  • useDeleteMany calls dataProvider.deleteMany()

Their input signature is the same as the related dataProvider method, e.g.:

const [update, { isPending, error, data }] = useUpdate(resource, {
  id,
  data,
  previousData,
});
// calls dataProvider.update(resource, { id, data, previousData })

For instance, here is a button that updates a comment record when clicked, using the useUpdate hook:

import { useUpdate, useRecordContext } from "ra-core";
 
const ApproveButton = () => {
  const record = useRecordContext();
  const [approve, { isPending }] = useUpdate("comments", {
    id: record.id,
    data: { isApproved: true },
    previousData: record,
  });
  return (
    <button onClick={() => approve()} disabled={isPending}>
      Approve
    </button>
  );
};

For more information and examples, refer to the Data Fetching documentation.